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Vaxeln  Experimentation: 
Programming  a  Real-Time  Clock  and 
Interrupt  Handling  Using  Vaxeln  Ada  1.1 


Abstract:  This  report  describes  the  results  of  implementing  an  interrupt  handler  totally  in 
Ada  for  a  MicroVAX  ii/Vaxeln  2.3  target  system,  the  Vaxeln  1.1  Ada  compiler,  and  a 
KWV1 1-C  programmable  real-time  clock.  It  provides  an  overview  of  Vaxeln  interrupt  hand¬ 
lers  and  the  operation  of  the  real-time  clock:  discusses  and  demonstrates  the  use  of 
Vaxeln  kernel  services  to  establish  a  link  between  the  clock’s  interrupt  and  the  starting 
address  of  an  interrupt  service  routine;  presents  an  Ada  package  of  interfaces  to  the 
KWV11-C  device:  provides  Ada  source  code  examples  demonstrating  the  use  of  this  pack¬ 
age:  and  presents  relevant  observations,  recommendations,  and  measurement  results. 


1.  Introduction 

This  paper  provides  the  reader  with  technical  information  and  observations,  Ada  source  code,  and  the 
results  of  our  work  in  developing  a  real-time  clock  interface  in  Ada.  The  results  are  specific  to  a 
MicroVAX  II/Vaxeln  2.3  target  system,  the  Vaxeln  1.1  Ada  compiler,  and  a  KWV1 1-C  programmable 
real-time  clock;  and  they  provide  answers  for  such  questions  as: 

•  How  does  one  write  an  interrupt  sen/ice  routine  (ISR)  in  Ada? 

•  How  is  an  Ada  ISR  associated  with  the  occurrence  of  a  hardware  device  interrupt? 

•  How  can  one  control  the  operation  of  a  KWV1 1-C  programmable  real-time  clock  using  an 
Ada  interface? 

1.1.  Background 

We  originally  intended  to  investigate  programming  alternatives  available  to  a  real-time  application 
developer  for  writing  an  interrupt  handler,  along  with  other  appropriate  Ada  routines  for  a  programm¬ 
able  real-time  clock.  Our  approach  was  to  code  a  simple  Ada  application  which  included: 

•  A  main  program  that  directs  the  real-time  clock  to  generate  interrupts  at  a  frequency  of 
500  Hz,  either  through  an  existing  interface  or  a  newly  developed  one. 

•  A  simple  application  task  scheduler  that  logs  a  message  to  an  external  text  file  when  it  is 
called  by  the  interrupt  service  routine. 

•  An  interrupt  service  routine  that  handles  time  interrupts  by  invoking  the  application  task 
scheduler. 

Within  this  framework,  the  main  program  is  also  responsible  for  opening  and  closing  the  log  file, 
enabling  and  disabling  the  timer  interrupts,  establishing  the  connection  between  the  clock’s  interrupt 
vector  and  the  service  routine’s  starting  address,  and  programming  the  clock  rate.  We  originally 
intended  to  analyze  both  the  run-time  costs  and  software  engineering  tradeoffs  (e.g.,  time  and  space 
performance,  maintainability)  associated  with  the  implementation  alternatives;  specifically,  we 
planned  to  measure  the  interrupt  handlers  execution  speed,  object  code  size,  and  the  associated 
interrupt  latency.  However,  we  found  only  one  alternative  for  implementing  an  interrupt  handler  totally 
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2.  VAXELN  Kernel 


In  contrast  to  the  general  purpose,  time-sharing  Vax/VMS  operating  system,  Vaxeln  [DEC  85,  DEC 
86a]  is  a  compact,  more  specialized  run-time  executive  which  supports  the  execution  of  application 
programs  on  "bare"  Vax  (i.e.,  no  operating  system  support  present)  target  machines.  In  particular, 
Vaxeln  Ada  applications  running  on  "bare"  Vax  target  machines  are  supported  entirely  by  the  Vaxeln 
run-time  executive  (i.e.,  kernel),  by  Vaxeln  services  (e.g.,  file  server),  and  by  the  Vaxeln  Ada  run¬ 
time  library.  For  an  application  system  running  under  the  Vaxeln  execution  environment,  these 
modules  must  be  linked  with  the  application’s  object  code  to  produce  a  system  load  module  (see 
Figure  2-1). 


Figure  2-1:  Vaxeln  Build  Process 

The  Vaxeln  kernel  is  a  layer  of  software  between  the  Vax  processor  and  application  code.  It  pro¬ 
vides  mechanisms  to  communicate  between  processes;  to  control  system  resource  usage;  to  create, 
suspend,  resume,  and  delete  jobs  and  processes;  to  schedule  jobs  and  processes;  and  to  maintain 
information  about  the  user  programs  defined  for  a  particular  system.  In  a  sense,  the  kernel  is  object- 
based  since  it  exports  most  of  its  services  through  a  set  of  procedures  and  functions  (i.e.,  operations) 
which  manipulate  kernel  objects  (i.e.,  data  structures).  The  predefined  kernel  objects  include:  AREA, 
DEVICE.  EVENT,  MESSAGE,  NAME,  PORT,  PROCESS,  and  SEMAPHORE.  The  operations  de¬ 
fined  for  these  objects  include  creation,  deletion,  assignment,  and  comparison. 


2.1.  Interrupt  Handling 

The  Vaxeln  kernel  supports  the  notion  of  interrupt  service  routines  (ISRs)  for  handling  device  inter¬ 
rupts  in  software.  Since  an  ISR  is  invoked  directly  by  the  Vaxeln  kernel  each  time  the  device 
generates  an  interrupt,  the  ISR  has  the  responsibility  of  taking  appropriate  action  to  service  those 
interrupts.  A  Vaxeln  kernel  service,  namely  CREATE_DEVICE  (see  Figure  2-2)  establishes  such  a 
connection  between  a  hardware  interrupt  and  an  ISR. 
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System  Control  Interrupt  Service 


Figure  2-2:  Associating  a  Device  Interrupt  with  an  ISR  Via  System  Control  Block  Entry 

This  kernel  service  places  the  starting  address  of  the  ISR  into  the  processor’s  system  control  block 
(SCB)  [DEC  84]  in  order  to  link  a  device's  interrupts  to  the  ISR.  At  invocation,  the  CREATE_DEVICE 
procedure  requires  a  device  name,  an  interrupt  vector  number,  and  starling  address  of  the  ISR  (which 
must  match  the  information  specified  during  the  system  build  process;  see  Figure  2-1).  In  return,  the 
out  pa  ameters  are  the  device's  base  address  (i.e.,  the  address  of  its  first  control/status  register),  the 
address  of  a  communication  region  that  can  be  shared  by  an  application  and  an  ISR,  and  a  Vaxeln 
device  object.  The  application  code  subsequently  uses  the  device  object  to  synchronize  with  the 
device’s  corresponding  ISR. 

2.2.  Synchronizing  the  Application  with  Intercepts 

The  Vaxeln  kernel  employs  an  object-based,  signal/wait  model  (see  Figure  2-3)  for  synchronizing 
application  code  with  the  hardware  interrupts.  Specifically,  the  kernel  treats  the  device  object 
returned  from  a  CREATE_DEVICE  call  as  a  binary  semaphore.  When  an  interrupt  occurs,  the  kernel 
invokes  the  appropriate  ISR,  which  must  signal  the  occurrence  of  the  interrupt  through  the  cor¬ 
responding  device  object.  This  signaling  is  performed  by  a  call  to  the  non-blocking  SIGNAL_DEVICE 
kernel  service  which  sets  the  value  of  the  device  object  (i.e.,  binary  semaphore).  The  application 
code  synchronizes  with  an  ISR  and,  therefore,  with  the  occurrence  of  a  particular  interrupt  by  waiting 
for  this  device  signal,  using  either  the  WAIT_ANY  or  WAIT_ALL  kernel  service  (see  [DEC  86b]  for 
further  details).  Calls  to  these  services  suspend  until  the  specified  conditions  (in  this  case,  a  device 
object  value  of  at  least  one)  are  satisfied  or,  optionally,  a  timeout  occurs;  if  a  wait  on  a  device  signal  is 
satisfied,  the  device  object's  value  is  reset  to  zero. 
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Figure  2-3:  Vaxeln  Signal/Wait  Synchronization  Model 


2.3.  Data  Sharing 

The  ISR  and  application  code  share  data  through  an  interrupt  communication  region.  For  example, 
the  ISR  passes  data  to  the  application  code  by  reading  the  device  data  registers  and  placing  the 
values  into  the  communication  region  for  later  use  by  the  application.  The  ISR  receives  the  starting 
address  of  the  communication  region  as  a  parameter  from  the  Vaxeln  kernel;  subsequently,  the 
application  code  uses  the  data  region  address  returned  by  the  CREATE_DEVICE  to  access  this 
shared  region. 
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3.  KWV11-C  Programmable  Real-time  Clock 

The  KWV1 1  -C  printed  circuit  board  is  a  programmable  real-time  clock  that  is  Q-bus  compatible. 


3.1.  Functional  Description 

The  KWV11-C  supports  five  clock  rates  (1  MHz,  100  KHz,  10  KHz,  1  KHz=z,  100  Hz),  which  are 
derived  internally  from  a  10  MHz  crystal  oscillator.  The  device  has  a  16-bit  counter  that  can  generate 
processor  interrupts,  four  programmable  operation  modes,-  and  two  Schmitt  triggers,  each  with  slope 
and  level  controls  that  can  start  the  clock  or  generate  interrupts.  Refer  to  [DEC  86c]  for  further  details 
about  the  Schmitt  triggers. 

The  KWV11-C  can  generate  two  distinct  interrupts,  clock  overflow  and  Schmitt  trigger,  and  therefore 
requires  two  interrupt  vectors.  It  has  two  read/write  device  registers  that  can  be  addressed  by  the 
processor;  a  control/status  register  (CSR)  and  buffer/preset  register  (BPR).  The  CSR  allows  you  to 
control  the  operation  of  the  device  (e.g.,  enable  interrupts,  select  clock  rate,  start  the  internal  counter) 
and  to  query  regarding  its  current  operating  status.  The  BPR  supports  two  different  functions  de¬ 
pending  on  the  clock's  current  mode  of  operation;  both  functions  deal  with  interfacing  with  the  clock's 
counter.  In  one  case  (Modes  0  and  1 )  it  provides  a  mechanism  for  the  loading  the  counter,  and  in  the 
other  (Modes  2  and  3)  it  provides  indirect  reading  of  the  counter's  current  value. 

3.2.  Modes  of  Operation 

The  KWV1 1  -C  can  operate  in  any  one  of  four  modes: 

Mode  0  Single  Interval  Interrupt:  The  GO  command  (i.e.,  setting  the  GO  bit  of  the  clock's 
CSR)  is  used  to  load  the  counter  with  the  2's  complement  of  the  number  of  ticks  to 
wait  before  generating  an  interrupt.  The  counter  increments  at  the  selected  clock  rate 
until  an  overflow  occurs  and  an  interrupt  is  generated  (assuming  the  INTOV  flag  of  the 
CSR  is  set ).  It  then  waits  for  another  GO  command. 

Mode  1  Repeated  Interval  Interrupts:  Same  as  Mode  0  except  that  the  counter  is  re-loaded 
and  continues  counting  after  it  overflows.  This  mode  supports  repeated  interrupts 
whose  period  is  the  value  in  the  BPR. 

Mode  2  External  Event  Timing:  The  counter  increments  at  the  selected  clock  rate  and  upon 
input  (i.e.,  high  logic  signal)  at  Schmitt  trigger  #2,  its  contents  are  loaded  into  the  BPR, 
where  the  value  can  be  read.  This  firing  of  Schmitt  trigger  #2  can  be  simulated  under 
program  control  by  setting  the  MAIN_ST2  bit  of  the  clock’s  CSR.  In  this  mode,  the 
counter  continues  without  interruption. 

Mode  3  External  Event  Timing  Zero  Base:  Same  as  Mode  2  except  that  the  counter  is  reset  to 
zero  after  its  contents  are  loaded  into  the  BPR. 
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3.3.  Program  Control 

This  section  presents  typical  programming  scenarios  that  can  be  used  to  control  the  KWV11-C  tor 
each  of  its  operational  modes.  We  assume  that,  where  necessary,  interrupt  service  routines  are 
already  associated  with  the  clock’s  interrupts.  Appendix  B  contains  sample  Ada  code  corresponding 
to  each  scenario. 

Single  Interval  Interrupt  (Mode  0) 

1 .  Load  the  BPR  with  the  2’s  complement  of  the  number  of  dock  ticks  to  wait  before 
generating  an  counter  overflow  interrupt. 

2.  Load  the  CSR  with  the  appropriate  settings:  mode  0,  desired  clock  rate,  and  the  inter¬ 
rupt  enable  flag  (INTOV)  set  to  TRUE. 

3.  Set  the  CSR’s  GO  bit  to  load  the  counter  from  the  BPR.  The  counter  increments  at  the 
selected  clock  rate  until  it  overflows.  A  counter  overflow  interrupt  is  generated,  and  the 
CSR  overflow  flag  (OVFLO)  flag  is  set. 

4.  To  repeat  this  process,  clear  the  overflow  flag  (OVFLO)  and  set  the  GO  bit. 

Repeated  Interval  Interrupts  (Mode  1) 

1 .  Load  the  BPR  with  the  2's  complement  of  the  number  of  clock  ticks  representing  the 
period  at  which  counter  overflow  interrupts  are  to  be  generated. 

2.  Load  the  CSR  with  the  appropriate  settings:  mode  1,  desired  clock  rate,  and  the  inter¬ 
rupt  enable  flag  (INTOV)  set  to  TRUE. 

3.  Set  the  CSR’s  GO  bit  to  load  the  counter  from  the  BPR.  The  counter  increments  at  the 
selected  clock  rate  until  it  overflows.  The  count  value  is  then  re-loaded  from  the  BPR, 
an  counter  overflow  interrupt  is  generated,  and  the  CSR  overflow  flag  (OVFLO)  flag  is 
set. 

4.  To  allow  subsequent  interrupts,  the  overflow  flag  (OVFLO)  must  be  cleared.  If  a  sec¬ 
ond  counter  overflow  occurs  before  the  flag  is  reset,  the  flag  overrun  (FOR)  bit  is  set. 

5.  To  stop  the  clock  from  generating  interrupts,  clear  the  CSR's  GO  bit. 

External  Event  Timing  (Mode  2) 

In  this  mode,  interrupts  can  be  generated  while  monitoring  external  events;  external  events  can  be 
counted;  and  the  elapsed  time  of  external  events  can  be  recorded.  The  scenario  below  addresses 
only  the  latter  application. 

1 .  Load  the  CSR  with  the  appropriate  settings:  mode  2,  and  desired  clock  rate. 

2.  Set  the  CSR’s  GO  bit  to  start  the  counter  at  the  beginning  of  the  external  event  that  is  to 
be  timed.  At  this  point,  the  counter  is  cleared  and  begins  incrementing  at  the  selected 
clock  rate. 

3.  Upon  completion  of  the  timed  event,  simulate  an  external  event  by  setting  the  mainte¬ 
nance  flag  of  the  the  second  Schmitt  trigger  (MAIN  ST2).  This  input  at  ST2  causes  the 
contents  of  the  counter  to  be  loaded  into  the  BPR  and  sets  the  ST2  interrupt  flag 
(INT2).  Note:  the  counter  continues  ticking. 

4.  Accessing  the  value  stored  in  the  BPR  gives  the  number  of  counter  ticks  that  elapsed 
since  the  CSR's  GO  bit  was  set  and  the  ST2  input  occurred. 

5.  To  stop  the  clock’s  counter,  clear  the  CSR’s  GO  bit. 
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This  section  presents  information  specific  to  implementing  an  Vaxeln  Ada  interface  for  a  KWV11-C 
device  operating  within  a  MicroVAX  II/Vaxeln  2.3  target  environment.  We  also  discuss  the  process  of 
handling  device  interrupts  with  Vaxeln  Ada  code. 


4.1.  Access  to  Device  Registers 

The  KWVii-C  has  two  16-bit  read/write  device  registers,  the  control/status  register  (CSR)  and  the 
buffer/preset  register  (BPR).  The  CSR  allows  you  to  control  the  operation  of  the  device  (e  g.,  enable 
interrupts,  select  clock  rate,  start  the  internal  counter)  and  to  query  regarding  its  current  operating 
status.  The  BPR  supports  reading  from  and  writing  to  the  clock's  counter.  At  the  lowest  level  of  the 
KWV11-C  interface,  data  types  must  be  defined  and  laid  out  using  Ada  representation  specifications 
to  allow  full  access  to.  and  control  of,  the  contents  of  the  device  registers.  The  following  Ada  package 
serves  this  purpose. 

with  SYSTEM;  uaa  SYSTEM; 

with  VAXfXN_SERVICES; 

packaga  KWV_Ra<ji»tar_Daf l_nit iona  ia 


KWV11-C  Control  8tatua  Ragiatar  layout 


type  KMVCSRJRacord  la  racord 


go 

BOOLEAN; 

mode 

UNSIGNED  2 

rate 

UNSIGNED  3 

int_ovf 

BOOLEAN 

ovf_flag 

BOOLEAN 

amlnt_atl 

BOOLEAN 

naint_at2 

BOOLEAN 

amint_oac 

BOOLEAN 

dio 

BOOLEAN 

f 1 ag_o ve rrun 

BOOLEAN 

at  2_go_anabla 

BOOLEAN 

at  2_int_enable 

BOOLEAN 

at2_flag 

BOOLEAN 

and  racord; 


—  a tart  tha  countar 

—  aoda  of  o pa ration 

—  dock  rata 

—  anabla  lntarrupt  on  overflow 

—  countar  overflow  occurred 

—  eimulate  firing  of  atl 

—  aimulata  firing  of  at 2 

—  aimulata  one  cy.  of  oac 

—  diaable  internal  oacillator 

—  Interrupt  overrun 

—  aaaartion  of  at2_flag  aeta  go  bit 

—  aaaartion  of  at2_flag  cautaa  an  interrupt 

—  atart  interrupt  request  for  at2 


for  KWV  CSR  Record  uaa  racord  at  mod  2; 


go 

at 

0 

rang* 

0.  .0 

*  * 

mode 

at 

0 

rang* 

1.  .2 

rate 

at 

0 

rang* 

3.  .3 

S' 

int_ovf 

at 

0 

rang* 

6.  .6 

& 

ovf  flag 

at 

0 

rang* 

7.  .7 

maint  atl 

at 

0 

rang* 

S.  .1 

amint~at2 

at 

0 

rang* 

9.  .9 

amint__oac 

at 

0 

rang* 

10. .10 

\ 

dio 

at 

0 

rang* 

11.  .11 

flag_overrun 

at 

0 

rang* 

12.. 12 

at2_go_anabla 

at 

0 

rang* 

13.. 13 

a  • 

A 

at  2_lnt_anabla 

at 

0 

rang* 

14.  .14 

k 

at2_flag 

at 

0 

rang* 

15. .15 

and  record; 
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for  KMV  C8R  Record' 8XZE  uao  16; 


—  KKV11-C  Buff or /Pro sot  Regia tor  layout 


aubtypo  KWVJBPR_Typo  la  VAXEXN_8ERVICES . KWV_COUNTER_TYPE ; 


Raoord  typo  oontolnlng  tbo  KWV11-C' a  CSR  and  Buff or /Proa at  Rogiatar 


typo  KMV_Roglatara  la  raoord 

CSR  :  KWV_CSR_Roc©rd;  —  control /atatua  rogiatar 
BPR  :  KWV_BPR_Typo ;  —  buf for/proaot  rogiatar 

and  raoord; 

pragma  PACK (KWV_Rogiatora) ; 


proooduro  Put_CSR  (CSR  :  In  KWV_C8R_Rooord; 
Roglator_Addroaa  :  In  ADDRESS  ) ; 


function  GotjCSR  (Roglator_Addroaa  :  In  ADDRES8)  rot urn  KWV_CSR_Rocord; 


and  KHV_Roglator_Doflnltlona; 

This  package  also  provides  two  primitive  operations  for  reading  and  writing  the  contents  of  the  clock's 
control/status  register,  namely  Put_CSR  and  Get_CSR. 


4.2.  Ada  Interrupt  Service  Routine 

When  writing  an  interrupt  service  routine  (or  any  Ada  subprogram)  that  will  be  invoked  by  the  Vaxeln 
kernel,  the  following  requirements  must  be  satisfied  to  ensure  proper  run-time  behavior  [DEC  86d], 

•  Each  subprogram  must  either  be  a  stand-alone  program  library  unit  or  must  be  declared 
at  the  outer-most  level  of  a  library  package  (i.e.,  its  specification  or  body). 

•  The  subprogram  s  name  must  be  exported  via  the  appropriate  Vaxeln  Ada  pragma  (e  g., 
EXPORT_PROCEDURE)  in  order  to  resolve  any  external  references  during  linking. 

•  The  subprogram  must  be  compiled  with  a  pragma  SUPPRESS_ALL  to  disable  stack 
overflow  and  underflow  checks  that  would  otherwise  fail  when  invoked  on  the  kernel 
stack. 

•  The  subprogram  must  avoid  using  Ada  tasking  operations  and  input/output  operations, 
and  should  minimize  the  calls  to  external  subprograms. 

The  following  is  a  minimal  ISR  coded  in  Ada. 

with  SYSTEM; 

with  VAXELNJBEKVZCES;  uao  VAXELN_8ERVXCXS; 

with  CO»TDItTo*T_HAHDLING; 

with  KMV_Roglator_Doflnltleas;  uao  KMV_Roglator_Dof laltlcna; 

proooduro  Tlaar_Xntarrupt_Routlno (  Dorloo_Roglatora  :  In  out  KMV_Roglatora ; 

Interrupt  Region  :  In  SYSTEM. ADDRESS; 

ISR  Contest  :  In  1 SR_COMTEAT_TYPE  )  la 

Rotum_Codo  :  CCtTDITIOW_HANDLIHG.  COWD_VXLOE_TYPE; 

bog  In 
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VAXELN_SERVICXS .  8ignal_D«vio«  (Statu*  “>  R«tum_Cod« , 

D*vic«_Nuab«r  “>  0, 

ISR_Cont*xt  “>  ISR_Cont«xt  ) ; 

•nd  Tia»r_Xnt«rrupt_Routin«; 

pragma  EXPORT  PROCEDURE (Timar_Intarrupt_Routina) ; 
pragma  S0PPRESS_ALL; 


To  use  this  ISR  you  would  "with"  the  subprogram  and  then  use  Timer_lnterrupt_Routine' ADDRESS 
as  the  address  of  the  service  routine  in  a  CREATE_DEVICE  call.  For  example,  the  following  code 
associates  the  clock's  counter  overflow  interrupt  (first  interrupt  vector)  with  the 
Timer_lnterrupt_Routine  ISR. 

with  SYSTEM; 
with  VAXELH_SERVICES; 
with  COMDITIOM_BAMDLZVC; 
with  TiMr_Zatarrupt_Routiaa; 

procadura  I SR_Exaspl a  is 

Davica_Maam~  :  oooatant  STRING  "KWV11"; 

Ra^"*  atara  :  SYSTEM.  ADDRESS; 

R»tam_Coda  :  COMDITIOB_HANDLING. COND_VALOE_TYPE; 

TiaarjDavioa  :  VAXELN_SERVICES . DEVICE_ARRAY_TYPE (0 . . 0)  :«  (othara  ->  0) ; 

bag  in 

Craata_Davioa  (Statu a  ■>  Ratuxn_Coda, 

DawioaJRama  ■>  DaTioa_Nama, 

Vaotor_Nuabar  ■>  1 , 

Sarrioa_Routina  a>  Timar_Intarrupt_Rout  ina '  ADDRESS , 

Ragiatara  ■>  Ragiatara, 

Davioa_Array  ■>  Timar_Dawioa, 

Dawioa_Count  •>  X) ; 

and  I SR_Exampl a ; 

Note  that  the  string  name  of  the  device  being  created  must  match  the  name  of  a  device  specified  in 
this  program's  Vaxeln  build  file  (see  Figure  2-1).  For  instance,  a  typical  build  file  for  the  main 
program  might  look  like  this: 

program  ISR_Exampla  /dabug  /aoda^carnal 

davica  KHVX1  /ragi»tar«*0770420  /▼actor“%044 0  /noautoload 
t a rain a 1  CONSOLE  /hardcopy 


4.3.  Device  interface 

The  package  specification  listed  below  provides  the  necessary  data  types,  procedures,  functions,  and 
exceptions  for  interfacing  to  multiple  KWV1 1  -C  real-time  clocks  using  Ada  application  code.  These 
routines  support  all  four  modes  of  the  clock's  operation  in  addition  to  its  five  internal  clock  rates: 
however,  only  counter  overflow  interrupts  are  supported  and  not  Schmitt  trigger  interrupts  The 
VAXELN  Ada  kernel  services  (KWVJNITIALIZE,  KWV  READ,  KWV_WRITE)  provide  the  necessary 
interfaces  for  supporting  the  handling  of  the  clock's  Schmitt  trigger  interrupts.  This  Ada  package 
specification  is  listed  again  in  Appendix  A  along  with  its  corresponding  body. 
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with  VAXELH_8ERVICES,- 
with  CONDITION  HANDLING; 
with  SYSTEM;  ~ 


package  KWVll_Clock_Manager  ia 


-  Data  type*  imported  f  roe  SYSTEM  package 
aubtypa  ADDRESS  is  SYSTEM. ADDRESS; 


-  Data  types  imported  frost  CONDITION_HANDLING  package 
subtype  OOND_VXLOE_TYPE  is  CONDZTZON_HANDLZNG. COND_VAZ.OE_TYPE; 


—  Data  types  iaqported  frost  VAXELN_8ERVZCES  package 


subtype  DEVICE_TYPB  is  VAXELN  SERVICES .  DEVICE  TYPE; 

subtype  KKV_CODHTER_TYPE  is  VAXELlTsERVICES . KWV_CODNTER_TYPE ; 
subtype  VECTOR_NUMBER_TYPE  is  VAXE1N_8ERVZCE8 . VECTOR_HUMBER_TYPE; 


—  Local  Data  types 

type  Clock_ID  is  private; 

type  Clock_Mode  is  (Moda_Zexo ,  Mode_One,  ModeJTwo,  Mode_Three) ; 


for  Clock_Mode  use  (Moda_Zero  ■>  0,  ModeOne  •»>  1, 
Mode_Two  <■>  2,  ModeJThree  «>  3); 


type  Cloek_Rate  is  (Stop,  Rat el MHZ,  Ratal 00KHZ, 

Ratal OKHZ,  RatelXHZ,  Ratal 00HZ) ; 


for  Clock_Rate  use  (Stop  ■>  0,  RatelMHZ  ■>  1, 

RatelOOKHZ  ->  2,  Ratal OKHZ  ->  3, 
RatelXHZ  ■>  4,  Ratal 00HZ  »>  5) ; 


initialise  (Clock_Kane 

In 

STRING; 

Clock  Identifier 

out 

Clock  ID; 

Mode 

In 

Clock  Jlode; 

Rate 

in 

Clock  Rate; 

Vector_Vwsber 

in 

VECT0i_NDMBER  TYPE. 

Servi oe_Rout ine 

in 

ADDRESS ; 

CSR_Address 

out 

ADDRESS; 

Device_0bjeot 

out 

DEVZCE_TYPE  ) ; 

procedure  Reinitialise  (Clock_Zdentif ier  :  in  Clock  ZD; 

Mode  :  in  Clock'Hode; 
Rate  :  in  Clook_Rate  ) . 


procedure 

procedure 

procedure 


procedure 

procedure 


Display_C8R 

Enable_Znter rupt s 

Disahle_Znterrupts 

Pans  rete_Znterrupt  s 

Reset_Znterrupt_riag 

Reset_Overrun_Plag 

Set_Znterrupt_Period 


(Cloek_Zdentifier 
(Clook_Zdantifier 
(Clock_Zdantifier 
(Clock_Zdantif ier 
(Clock~Zdantifier 
(Clock  Identifier 
(ClockZdantifier 
Period 


in  Clock_ZD)  ; 
in  Cloek_ZD)  ; 
in  Clock_ZD)  ; 
in  Clock_ZD)  ; 
in  CloekiD)  ; 
in  Clock  ZD)  ; 
in  Clock~ZD; 
in  KWV_COOHTER  Type  ); 
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(Clock_Identif ier  :  in  Clock_ZD) ; 

(Clook_Identif ier  :  in  Clock_ID; 

Nuaber_Of_Tieke  :  out  KWV_COUNTER_Type) ; 
(Clook_Idantifier  :  in  Clock_ID; 

Nu«ber_Of_Tick«  :  out  KWV_COUNTER_Type) ; 

function  Interrupt »_Enabled  (Clock_Zd*ntifior  :  in  Cloek_ID)  rotum  BOOLEAN; 

function  Current_Mod«  (Clook_Identif ier  :  in  Clock~ZD)  rotum  Clock_Mode; 

function  Curront_ltato  (Clook_Zdontifior  :  in  Clock_ZD)  rotum  Clock_Rate; 

function  Zntorrupt_Poriod  (Clock_Zdontifior  :  in  Clock_ZD)  rotum  KHV_COONTER_Typo 

function  Zntorrupt_riog_On  (Clock_Zdontifior  :  in  ClockID)  rotum  BOOLEAN; 

function  OworrunjrT*g_Cta  (Clock_Zdontifior  :  in  Clock_ZD)  rotum  BOOLEAN; 

ZnvoZid_Clock_Modo  :  EXCEPTION; 

Znitiolixotion_Error  :  EXCEPTION; 

Clock_Not_Initiolicod  :  EXCEPTION; 

private 

aubtypo  Ciock_ZO_Rangro  ia  NATURAL  ranyo  0.  .31; 
typo  Clock_ID  ia  now  Clock_ID_Range; 

ond  KHVH_Clock_Managor; 


4.4.  Using  the  Device  Interface 

4.4.1.  Initializing 

The  Initialize  procedure  creates  a  Vaxeln  device  object  for  the  clock  and  gives  you  a  private  clock 
identifier.  The  Vaxeln  device  object  can  be  used  by  the  application  to  "wait"  via  a  Vaxeln  kernel  call 
on  a  device  signal  originating  from  an  interrupt  service  routine.  The  clock  identifier  is  a  key  for 
invoking  all  other  subprograms  in  the  package.  The  lnitia!ization_ErTor  exception  is  raised  if  the 
Vaxeln  kernel  device  object  cannot  be  created.  The  clock’s  rate  and  mode  are  set  by  the  Initialize 
procedure  and  can  be  reset  using  the  Rejnitialize  procedure;  however,  the  address  of  the  ISR 
associated  with  the  clock's  counter  interrupt  can  only  be  specified  through  the  Initialize  interface.  The 
Current_Rate  and  Current_Mode  functions  respectively  return  the  clock's  current  rate  and  mode  as 
set  by  either  the  Initialize  or  Rejnitialize  procedure.  The  Display_CSR  subprogram  displays  the 
current  contents  of  the  clock’s  control/status  register  to  standard  output 

4.4.2.  Controlling  Operation 

The  following  routines  can  be  used  to  control  the  operation  of  the  clock  and  to  query  regarding  its 
current  operating  status;  Enable  Jnterrupts,  Disable  .Interrupts,  Set_lnterrupt_Period, 
Generatejnterrupts,  ResetJntemjpt_Flag,  Reset_Overrun_Flag.  lnterrupts_Enabled, 
lnterrupt_Period,  lnterrupt_Flag_On,  Overrun_Flag_On.  Given  a  valid  CtockjD,  these  routines  set. 
reset,  and  query  current  values  for  the  various  bit  fields  of  the  CSR  and  BPR  associated  with  the 
clock  device  represented  by  the  dock  identifier.  A  brief  functional  description  of  each  of  these  sub 
programs  follows: 

Enablejnterrupts  Set  the  lnt_ovf  bit  of  the  deck's  CSR  to  enable  interrupts  when  the 
internal  counter  overflows 

Disablejnterrupts  Reset  the  lnt_ovf  bit  of  the  clock's  CSR  to  disable  interrupts  when 
the  internal  counter  overflows. 


proewdur*  Start_Counting 
procadur*  Raad_Count*r 

procedure  8top_Counting 
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SetJntemjpt_Period  Load  the  2's  complement  representation  of  the  specified  number  of 
ticks  into  the  ckx*’s  BPR.  This  number  of  ticks  represents  the 
period  for  interrupt  generation. 

Generatejntenupts  Set  the  GO  bit  of  the  clock's  CSR  to  start  the  internal  counter.  This 
subroutine  is  used  in  conjunction  with  Enable  Jnterrupts. 

Reset _lnterrupt_Flag  Reset  the  ovf_flag  bit  of  the  clock's  CSR  to  allow  subsequent  inter¬ 
rupts. 

Reset_Overrun_F!ag  Reset  the  f!ag_overrun  bit  of  the  clock's  CSR.  This  bit  is  set  when 
a  counter  overflow  occurs  and  the  ovf_flag  has  not  been  reset  after 
the  last  interrupt.  This  indicates  that  the  hardware  is  generating 
interrupts  faster  than  the  software  can  service  them. 

lnterrupts_Enabled  Returns  a  Boolean  value  indicating  whether  or  not  the  lnt_ovf  bit  of 
the  clock's  CSR  is  set. 

lnterrupt_Period  Returns  the  current  interrupt  period  value  in  the  clock's  BPR. 

lnterrupt_Flag_On  Returns  a  Boolean  value  indicating  whether  the  ovf_flag  bit  of  the 

clock's  CSR  is  set. 

Ovenrun_Flag_On  Returns  a  Boolean  value  indicating  whether  the  flag_overrun  bit  of 
the  clock's  CSR  is  set. 

4.4.3.  Time  Measurements  for  External  Events 

The  Start_Counting.  Read_Counter.  and  Stop_Counting  procedures  provide  support  for  timing  exter¬ 
nal  events.  They  should  be  used  only  in  Modes  2  or  3.  In  any  other  mode,  the  lnvalid_Clock_Mode 
exception  will  be  raised.  The  distinction  between  Read_Counter  and  Stop_Counting  is  that  the 
counter  continues  to  tick  when  the  clock  is  read  by  the  Read_Counter  subprogram  and  stops  count¬ 
ing  otherwise.  These  routines  can  be  used  in  two  ways: 

1 .  Continuous  timing 

8tart_Countar  (Hy_Clock_ID)  ; 
loop 

Kaad_Count ar (My_Clock_ID ,  Huab«r_Of _Ti ck  a ) ; 
and  loop; 

8t.op_Count.ar  (My_Clock_ID)  ; 

2  Single  timing 


8t  art_Counta  r (My_Clock_ID) ; 

<  aaquanca  of  arants  to  ba  timad> 
Stop  Countar (My  Clock  ID); 
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4.4.4.  Miscellaneous 

Following  are  hints  for  using  these  routines: 

•  Be  sure  to  follow  the  restrictions  for  implementing  an  ISR  in  Ada.  See  Section  4.2  for 
details. 

•  The  three  most  likely  causes  of  the  lnitialization_Error  exception  are: 

1 .  The  device  name  specified  in  the  Initialize  call  cannot  be  found  in  the  list  of 
devices  created  by  the  System  Builder  from  the  main  program’s  build  file. 

2.  The  Initialize  procedure  was  called  from  a  program  that  was  not  running  in  kernel 
mode. 

3.  The  device  named  in  the  Initialize  call  is  already  connected  to  a  Vaxeln  device 
object. 

The  counter  routines  should  be  invoked  only  when  the  clock  is  operating  in  Mode  2  or 
Mode  3. 
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5.  Results 


This  section  presents  results  specific  to  developing  a  real-time  clock  interface  in  Ada  on  a  MicroVAX 
II/Vaxeln  2.3  target  system  using  the  Vaxeln  1.1  Ada  compiler  and  a  KWV11-C  programmable  real¬ 
time  clock.  These  results  take  the  form  of  technical  observations  relevant  to  an  application  devel¬ 
oper,  recommendations  to  the  compiler  implementor,  and  performance  measurement  results. 


5.1.  Technical  Observations 

We  made  the  following  observations  while  experimenting  with  Vaxeln  Ada  and  the  real-time  clock 
interfaces. 

1 .  To  redirect  standard  output  to  a  file  on  a  remote  DECnet  node,  the  File  Access  Listener 
option  must  be  turned  on  at  Vaxeln  system  build  time.  Furthermore,  the  file  that  will 
receive  the  output  must  exist  with  WORLD  read  and  write  access  enabled.  There  are 
two  alternatives  for  redirecting  output:  redefine  the  system  logical  SYSSOUTPUT  at 
build  time,  or  use  Ada  TEXTJO  routines  (OPEN,  PUT,  PUTJJNE,  CLOSE)  with  the 
remote  file  name. 

2.  There  are  guidelines  and  restrictions  for  writing  an  ISR  in  Ada.  See  Section  4.2  for 
details. 

3.  Using  the  /map  and  /full  qualifiers  on  the  EBUILD  command  yields  a  complete  map  of 
everything  in  a  program's  executable  load  module.  This  information  is  useful  for  ex¬ 
amining  the  CSR  and  vector  addresses  of  the  known  devices.  It  is  also  handy  for 
learning  which  device  drivers  are  being  loaded  along  with  your  main  program. 

4.  When  building  a  Vaxeln  application  that  calls  the  CREATE_DEVICE  service,  device¬ 
specific  information  must  be  provided  in  the  program's  Vaxeln  build  file  -  minimally,  the 
device  name  (a  string  matching  that  used  in  the  application's  CREATE_DEVICE  call), 
the  CSR  address,  the  interrupt  vector  address,  and  an  indication  as  to  whether  to  load 
the  standard  device  driver.  Additionally,  the  application  must  be  able  to  execute  in 
kernel  mode. 

5.  The  Vaxeln  service,  KWVJNITIALIZE,  results  in  an  access  violation  when  it  is  used  for 
re-initialization;  the  program  terminates,  which  is  incorrect  behavior. 

6.  An  Ada  block  with  local  variables  whose  memory  locations  are  specified  with  address 
clauses  provides  an  effective  way  of  accessing  data  stored  in  particular  locations  of 
memory.  For  instance,  the  KWV_READ  kernel  service  returns  the  starling  address  of 
the  data  it  fetches.  The  following  Ada  code  segment  illustrates  this  technique  for  ac¬ 
cessing  data  starting  at  a  specific  memory  address: 

KWV_READ  (Identifier  ->  Clock_ID, 

Value_Count  ■>  1,  “ 

Dete_Arrey_Ptr  ■>  Clock_Data_Address, 

8T2_Go_Enable  ->  FALSE, 

Status  “>  Retu  m_Oode  )  ; 

declare 

Ticks  :  INTEGER  : ■  0; 

Clock_Data  :  array  (0..0)  of  ONSIGNED_HORD; 
for  Clock_Data  use  at  Clock_Data_Address; 
begin 

Ticks  INTEGER (Clock_Data (0) )  ; 

Put_Line (INTEGER' IMAGE (Ticks) ) ; 
end; 
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7.  There  appear  to  be  at  least  two  alternatives  for  writing  to  and  reading  from  device 
registers  in  memory:  directly  assigning  locations  then  using  the  technique  described 
above  to  access  them  as  Ada  variables,  or  using  predefined  WRITE_REGISTER  and 
READ_REGISTER  subprograms.  However,  in  practice  .  the  first  alternative  cannot 
guarantee  correct  operational  behavior-the  generated  code  is  likely  to  contain  variable 
length  bit  field  instructions,  which  are  not  permitted  by  the  architecture,  for  accessing 
device  registers.  On  the  other  hand,  the  WRITE_REGISTER  and  READ_REGISTER 
subprograms  indicate  to  the  compiler  that  only  permissible  instructions  will  be  gener¬ 
ated:  therefore,  the  second  alternative  can  guarantee  proper  run-time  behavior.  The 
following  example  further  illustrates  this  point: 

Direct  Assignment 

DA. 05  procedure  Enable_Interrupts  (Clock  Identifier  :  in  Clock_ID)  ia 
DA.  OS 

DA. 07  Cu rr ent_CSR  :  KWV_CSR_Record; 

DA. 08  for  Current  CSR  uae  at  Clock  Array (Clock_Idantif ier) ; 

DA. 09 

DA.  10  begin 

DA. 17  if  Clock_Array (Clock_Identif ier)  /«  ADDRESS_ZERO  then 

DA.  18  Currant_CSR .  lnt_ovf  : «  TROT; 

»>  movzbt  01, r2 

»>  Inav  r2,06,01,(r3) 

»»  ret 

DA. 19  elae 

DA. 20  raise  Clock_Not_Initialired; 

DA. 21  end  if; 

DA. 22 

DA. 23  end  Enable_Interrupts; 

Read/Write  Register  Calls 

RW.06  procedure  Enable  Interrupts  (Clock_Xdantifier  :  in  Clock_ID)  is 
RW.07 

RW.08  Current_CSR  :  KWV_CSR_Record; 

RW.09  Temp  ;  ONSIGHED_WORD; 

RW.10  CSR_Unsigned  :  ONSICNED_WORD; 

RW.ll  for  CSR_Un signed  use  at  Clock_Array (Clock_Identif ier) ; 

RW.12 

RW.13  function  Convert_It  is  new  ONCHECKED_CONVERSION (ONSIGNED_WORD, 

KWV_CSR_Re  cord)  ; 

RH.14  function  Convert_It  is  new  ONCHECKED_COMVERSION(KWV_CSR_Record, 

ONSICNEDJWORD) ; 

KW.15 

RW.16  begin 

RM.23  if  Clock_Array (Clock_Idantif ier)  /■  ADDRESS_ZERO  then 

RH.24  Temp  READJREGISTER (CSR_Onaigned) ; 

»>  movw  (r1),r0 

»>  movw  r0,r2 

RW.25  Current_CSR  :■  Convert_It  (Temp)  ; 

»»  movw  r2,-20(fp ) 

»>  movab  - 16(fp),r3 

»>  movw  • 20(fp),(r3)+ 

Rif .  26  Current_GSR.  int_ovf  ;■  TROT; 

»>  movzbl  #1,r3 

»>  hev  r3, 06,01,-1 6(fp) 

lOt  .21  Tmop  ;■  Convert_It  (Current_CSR)  ; 

»>  movab  - 14(fp),r3 

>»  movw  - 16(fp),(r3 )* 

>»  movw  - 14(fp),r2 
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RW.28 

WRITZ_REGISTER(T«ap,  CSR_Oneigned) 

»> 

cvtwl  r2,r3 

»> 

movw  r3,(r1 ) 

»> 

ret 

RW.29 

•la* 

PW.30 

raiaa  Clock  Not  Initialized; 

RW.31 

end  if; 

RW.32 

RW.33 

and  Znabla_Interrupta ; 

The  generated  assembler  code  in  these  examples  (indicated  by  »>  at  the  start  of  the 
line)  shows  that  the  insv  (insert  variable  length  bit  field)  instruction  is  used  for  doing  the 
Boolean  assignment  current_CSR.int_ovf  :=  TRUE;  in  both  code  segments  (Line 
DA.18,  RW.26).  In  the  first  case,  the  base  operand  of  the  instruction  is  a  device 
register  and  will  yield  unpredictable  results.  In  the  second  case,  the  base  operand  of 
the  Insv  instruction  is  a  temporary  variable  that  later  performs  the  necessary  type  con¬ 
version  (Line  RW.27)  prior  to  the  WRITE_REGISTER  call.  Notice  that  the 
WRITE_REGISTER  call  generates  a  move  word  (movw)  instruction  (Line  RW.28)  for 
writing  to  the  device  register. 


5.2.  Recommendations 

1.  Vendors  should  supply  better  documentation  and  more  detailed  examples  of  Ada  ISRs. 
For  example,  the  present  documentation  does  not  explicitly  state  the  numbei  and  type 
of  ISR  parameters.  A  trouble-shooting  checklist  for  commonly  occurring  problems 
would  also  be  useful. 

2.  In  order  to  support  more  functionality,  the  restrictions  should  be  loosened  on  the  ISR 
code  to  avoid  Ada  tasking  operations  and  to  minimize  the  calls  to  external  sub¬ 
programs.  Task  entry  calls  should  be  permitted  from  within  an  ISR  in  order  to  provide 
an  interrupt  handling  capability  similar  to  the  one  suggested  in  the  Ada  Language  Ref¬ 
erence  Manual  (DoD  83). 


5.3.  Performance  Measurements 

For  each  example  of  Ada  code  presented  in  Appendix  B,  we  recorded: 

•  number  of  lines  of  code  (i.e.,  number  of  carriage  returns) 

•  number  of  statements  (i.e.,  number  of  semi-colons) 

•  object  code  size 

•  system  load  module  size 

We  also  used  the  KWV11-C  real-time  clock  to  measure  the  elapsed  time  from  when  the  hardware 
generates  an  interrupt  until  the  application  code  resumes  execution.  The  interrupt  latency  time  can 
be  more  accurately  measured  using  hardware  techniques  (e  g.,  logic  analyer)  and  still  must  be  done. 
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Vaxeln  Ada  Code  Sizes 


Program  Name  LOC  #  Stmts  Object  Code  Bytes  Load 

Size  (bytes)  Per  LOC  Module (bytes) 


ModeO_Test 

110 

44 

5632 

51.2 

305_152 

Model_Test 

118 

45 

6144 

52.1 

305__152 

Mode2_Test 

70 

30 

5120 

73.1 

304_128 

Mode3_Test 

76 

34 

5120 

67.4 

304_128 

We  used  two  software  measurement  techniques  to  measure  the  elapsed  time. 

Technique  #1 

The  essence  of  this  approach  is  to  start  at  an  interrupt  frequency  that  the  software  can  handle  and  to 
increase  this  frequency  until  the  software  can  no  longer  service  the  interrupts  fast  enough.  This  will 
give  a  rough  measure  of  the  time  elapsed  from  the  interrupt  occurrence  until  the  application  code  is 
re  scheduled  and  executed.  This  measurement  can  be  taken  by  operating  the  clock  in  Mode  1  and 
looping,  decrementing  the  interrupt  period  by  one  for  each  iteration  until  the  clock’s  overrun  flag  is 
set,  indicating  that  software  is  not  keeping  up  with  the  interrupt  rate.  The  following  pseudo  code 
represents  the  logic  of  this  technique  (see  Appendix  C  for  the  Ada  code  associated  with  this 
approach): 

Ticks  :«  5000; 
loop 

Ra-lnltlallza  clock 
Enabla  clock  overflow 
Tick*  : “  Ticks  -  1; 

Program  clock  to  ganarata  Interrupt  every  Ticks  microseconds 
Start  generating  the  Interrupts 

Walt  for  a  signal  device  (kernel  service)  call  from  the  I SR 
Reset  Interrupt  flag  to  allow  store  Interrupts  to  be  generated 

Exit  when  Overrun_Tlag_0n (My_Clock_ID) ; 
end  loop; 

Print  current  value  of  Ticks 

Technique  #2 

This  technique  is  direct  and  reliable.  It  can  be  performed  when  the  clock  is  operating  in  either  Mode  2 
or  Mode  3.  It  combines  the  counter-reading  capability  of  these  modes  with  the  fact  that  the  counter 
will  generate  interrupts  when  it  overflows,  regardless  of  the  mode  of  operation.  The  approach  is  to 
enable  counter  overflow  interrupts,  start  the  oounter,  wait  for  a  signal  from  the  ISR  caused  by  an 
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interrupt,  and  finally  read  the  current  counter  value.  The  following  pseudo-code  represents  the  logic 
of  this  technique  (see  Appendix  C  for  the  Ada  code  associated  with  this  approach): 

Enable  overflow  interrupt* 

Start  Counting 

Halt  for  a  aignal  device  (kernel  aervioe)  oall  from  the  I SR 
Stop  Counting  (read  current  counter  contents) 

Print  number  of  Ticks 


Vaxeln  Ada  Software  Interrupt  Latency  (nsec) 
(Each  average  based  on  25  data  points) 


Technique  #1 

Mode  2 

Technique  #2 
Mode  3 

Maximum 

time 

903.00 

331.00 

277.00 

Minimum 

time 

229.00 

270.00 

256.00 

Average 

time 

357.12 

274.20 

271.04 

Standard  Deviation 

237.87 

11.63 

4.70 
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Appendix  A:  KWV11_Clock_Manager  Source  Code 

A.a.  KWV_Register_Definitions  Package  Specification 


MI  Ada  tab*dd*d  tyitau  Project  Prologue 


—  Unit  name 

—  Experiment  # 

—  Version 

—  Author 

—  Data  ozaatad 

—  Last  updata 

—  Boat  Ha china 


KWV_Regieter_Def Inltiona  package  apaclf lcation 
PA01 
1.0 

Mark  W.  Borger 

20  Tab  1987 
12  Mar  1987 

VAXELN/VMS  4.5 


Tar gat  Ma china:  VAXELM  2.3 


—  Abatract 


Thla  packaga  apaclf lcation  provides  the  necaaaary 
data  typaa  to  aeeaaa  the  Control  Statua  and  Buffer 
regiatera  of  a  JCHV11-C  Real-time  programmable  clock. 


Reel a loo  Hiatory 


—  Data  Vera ion  Author  Hiatory 

--  12  Mar  87  1.0  Mark  W.  Bor  gar  Added  prologue 


End  of  Prologue 


with  SYSTEM; 

with  VAXELM  SERVICES; 


uaa  SYSTEM; 


package  KMV_Ragiatar_Daf inltiona  la 


KWV11-C  Control  Statua  Ragiatar  layout 


type  KWV_C8R_REC0RD  la  record 
go  ;  BOOLEAN; 

mode  :  0NSIGHED_2; 

rate  :  0NSIGNED_3; 

int_ovf  :  BOOLEAN; 

ovf_flag  ;  BOOLEAN; 

malnt_atl  :  BOOLEAN; 

malnt_at2  :  BOOLEAN; 

■alnt  oac  :  BOOLEAN; 

dlo  ~  :  BOOLEAN; 

f 1 ag_o va rrun  :  BOOLEAN; 

at 2_go_enabl a  :  BOOLEAN; 

at2~int  enable  :  BOOLEAN; 

st2_flag  :  BOOLEAN; 

and  record; 


—  atart  the  counter 

—  mode  of  operation 

—  dock  rata 

—  interrupt  on  overflow 

—  counter  overflow  occurred 

—  aimulate  firing  of  atl 

—  aimulate  firing  of  at2 

—  aiaulate  one  ey.  of  oac 

—  disable  internal  oacillator 

—  true  if  ovf  occurs  with  ovf_flag  still  sat 

—  assertion  of  st2_flag  sets  go  bit 

—  assertion  of  st2_flag  causes  an  interrupt 

—  start  interrupt  request  for  st2 
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2; 


i 


for  KMV  Ct>  RECORD  uae  rooord  «t  aod 


v> 

at 

0 

caage 

0.  .0 

■ode 

at 

0 

rang* 

1.  .2 

rate 

at 

0 

rang* 

3.  .5 

lnt_oef 

at 

0 

rang* 

4.4 

orf_flag 

at 

0 

rang* 

7.  .7 

aalat  *tl 

at 

0 

rang* 

«.  .1 

aalnt_at2 

at 

0 

rang* 

#.  9 

■a  1 nt_oac 

at 

0 

rang* 

10.  .10 

dio 

at 

0 

rang* 

11.  .11 

flag_oeerrun 

at 

0 

rang* 

12. .12 

at  2_go_enabl a 

at 

0 

rang* 

13  .13 

at  2_lnt_enable 

at 

0 

rang* 

14. .14 

at2~flag 

at 

0 

rang* 

15.  .15 

and  rooord; 

for  KMV  CSR  RECORD' SIZE  uao 

14; 

—  KMV11-C  Buffer/Proaot  Register  layout 


•ubtype  KWV_BPR_TYPK  la  VAXEUI_8ERVXCXS . KMV  COUNTER  TYPE; 


--  Rooord  typo  containing  tho  KMVll-C'a  CSR  and  Buf for/Proaot  Register 


typo  KMV_RECISTCRS  la  rooord 

C*R  :  KMV_CSR_RXCORD;  —  control /atatua  register 
■PR  ;  KMV_BPR_TYPE;  —  buf for/proaot  register 

and  rooord ; 

pragae  PACK (KMVJREGIBTERS) ; 


procoduro  Put_C8R  (CSR  :  in  KKV_CSR_Reoord; 

Roglator_Addzoaa  :  In  ADDRESS  ) ; 

function  Get_CSR  (Roglator_Addroaa  ;  In  ADDRESS)  rot urn  KMV  CSR  Record, 


and  KWV_Roglatar_Daf lnltlon* ; 


A.b.  KWV_Register_Definitions  Package  Body 


.* 

r 

> 


SSI  Ada  Tahaddad  System*  Project  Prologue 


--  Unit  naoa 
--  Experiment  « 
--  Vera ion 
—  Author 


KMV_Register  Deflnltlona  package  body 
PAOl 
1.0 

Mark  M.  Bo rye r 


--  Date  created 
--  Laat  update 


23  Mar  1117 
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—  Boat  Ha  china  :  VAXEIJi/VMS  4.S 

—  Tar Tat  Ua china:  VAXXTJI  2.3 


—  Abatract 


Thia  paokaga  body  providaa  tha  naoaaaary  Intarfaca 
for  raading  and  writing  tha  WVll-C'a  CSR. 


Data 


-  RaTiaion  Biatory  - 

Vara ion  Author  Biatory 


End  of  Prologua 


with  0MCBEC3CED_C0HVEBSI0H; 

packaga  body  KWV_Ragiatar_Daf lnitiona  ia 

function  Con ▼art  It  ia  naw  ONCHECKID_COWVERSIOH (KWV_CSR_Racord,  DNSIGNED_WORD) 
function  Coowart~Xt  ia  naw  0NC8SCSXD_C0NVERSI0H  (UNSIGNED_WORD,  KWV_CSR_Racord) 

procadura  PutCSR  (CSR  :  in  KWV_CSR_Raoord; 

Ragi atar_Addraa a  :  ia  ADDRESS  )  ia 

Cu r ran t_CSR  :  ORSIGHED_WORD; 

CSR_Onaignad  :  ORSXGHED~«K»U>; 

for  C8R_0naignad  uaa  at  Ragiatar_Addraaa ; 

bagin 

Curran t_C8R  Con<rart_It  (C8R)  ; 

NRITE  REGISTER (Currant_CSR ,  C8R_Onaignad) ; 
and  Put~C8R; 
pragaa  INLINE (Put_CSR) ; 

function  GatCSR  (Ragiatar_Addzaaa  :  in  ADDRESS) 
rat urn  KMV_C8R_Racord  ia 

CSR  :  KWVCSRRacord. 

Currant_CSR  :  DRSICKED_WORD, 

CSR_Onaignad  :  ONSIGHED_WORD; 

for  CSR_Onaignad  uaa  at  Ragiatar_Addraaa : 

bagin 

CurrantCSR  : -  READ_RECX STER (CSR_Onaignad) ; 

CSR  :•  ConTart_It  (Currant_CSR)  ; 
raturn  CSR; 
and  Gat_CSR; 
pragaa  INLINE (Gat_CSR, ; 


and  KHV  Ragiatar  Daf Initiona . 


A.c.  KWV11_Clock_Manager  Package  Specification 

■ea 

—  Unit  name 

KWV11  Clock  Manager 

—  Experiment  # 

PA01 

—  Version 

1.0 

—  Author 

Mark  W.  Borger 

—  Date  created 

17  Mar  1987 

—  Last  update 

18  Mar  1987 

—  Host  Machine 

VAXZLN/VMS  4.5 

—  Target  Machin« 

i:  VAXELN  2.3 

—  Abstract 


This  package  •pacification  provides  tba  necessary 
data  typaa,  procaduraa,  function* ,  and  ax caption a 
for  intar facing  to  ■ultipla  KWV11-C  real-time  clock* 

(0-bua  davioa)  via  Ada  application  coda.  All  four  mo da a 
of  tha  dock's  operation  ara  supported  in  addition  to 
its  five  different  internal  clock  rates .  To  use  these 
routines  one  aust  first  invoke  the  Initialise  procedure 
to  create  a  dock  devioe  object  and  get  a  clock  identifier. 
This  device  object  can  be  used  by  the  application  to  wait 
on  a  devioe  signal  frost  an  Interrupt  Service  Routine;  tha 
clock  id  is  used  as  a  key  for  the  remainder  of  tha  package ' s 
interfaces.  The  Initialisation  exception  is  raised  if 
tha  VAXELN  kernel  device  object  cannot  be  created  for 
whatever  reason.  The  Clock_Mot_Inltialised  exception  is 
if  a  specified  clock  id  is  invalid. 

These  routines  only  support  counter  overflow  interrupts 
and  not  Schmitt  trigger  interrupts.  The  counter  routines 
(8tart_Counting,  Read_Counter,  8top_Counting)  should  only 
be  used  in  modes  Moda_Two  or  Mode_Three;  when  used  in  any 
■od*  the  Invalid_Clock_Mode  exception  will  be  raised. 


Revision  History 


Date  Version  Author 

18  Mar  87  1.0  Mark  M.  Borger 

22  Mar  87  1.0  Mark  W.  Borger 


History 

Added  Display_CSR  procedure. 

Added  Invalid_Clock_Mode  exception. 


End  of  Prologue 


with  VAXELM_8ERVICE S; 
with  CONDITION  HANDLING; 
with  SYSTEM;  ~ 

package  XMVll_Clock_Maaager  is 


—  Data  types  imported  from  SYSTEM  package 
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•ASV 


aubtypa  ADDRESS  is  SYSTEM . ADDRESS ; 


—  Data  typaa  Import ad  from  CONDXTXON_HANDLXNG  packaga 


aubtypa  COND_VALOE_TYPE  la  COKDITIOH_HAKDLIHC.  COND_VALOE_TYPE; 


—  Data  typaa  importad  from  VAXELH_8ERV1CES  packaga 


aubtypa  DEVZCE_TYPE  la  VAXE LN_SER VT CE S . DEVT CE_TYP E ; 

aubtypa  KWV_OOONTER_TYPE  la  VAXE1M_SERVTCE8 .  KWV_C0C7NTER_rYI>E; 
aubtypa  VECTOR_NUHBER_TYPE  la  VAXELN_SERVICES . VECTOR_NUMBER_TYPE ; 


—  Local  Data  typaa 


typa  Clock_ID  la  prlvata; 

typa  Clock_Moda  la  (Moda_Zaro ,  Moda_Qna,  Moda_Two,  Moda_Thraa) ; 

for  Clock_Mo<la  uaa  (Moda_Zaro  •>>  0,  Moda_0na  «>  1, 
Moda_Tvo  *>  2,  Moda_Thraa  ■>  3) ; 

typa  Clock_Rata  la  (Stop,  RatalMHZ,  Ratal 00KRZ, 

RatalOKHZ,  RatalKHZ,  Ratal 00HZ ) ; 

for  Clock_Rata  uaa  (Stop  »>  0,  RatalMHZ  »>  1, 

Ratal 00KHZ  2,  RatalOKHZ  ->  3, 

RatalKHZ  •>  4,  Ratal 00HZ  »>  5) ; 


procadura  Initializa  (Clock_Nama  :  In  STRXNG; 

Clock_Idantlflar  :  out  Clock_ID; 

Mo da  :  In  Clock_Moda; 

Rata  :  In  ClockJRata; 

Vacto  r_Numbar  :  In  VECTOR_HOMBER_TYPE; 

SarvicaJRoutlna  :  In  ADDRESS; 

CSR_Addraaa  :  out  ADDRESS ; 

Davica_Objact  :  out  DEVI CE_TYPE  ) ; 

procadura  Ra_Xnitializa  (Clock_Zdantlfiar  :  In  Clock_ID; 

Moda  :  In  Clock_Moda; 

Rata  :  In  Clock_Rata  ) ; 


procadura  Di»play_CSR  (Clock_Idantlflar  :  In  Clock_ZD) ; 

procadura  Enabla_Xntarrupta  (Clock_Idantlflar  :  In  Clock_ID) ; 

procadura  Dlsabla_Intarrupta  (Clock_Idantlflar  :  In  Clock_XD) ; 

procadura  Ganarata_Xntarrupta  (Clock_Idantlflar  :  In  Clock_ZD) ; 

procadura  Raaat_Intarrupt_Flag  (Clock_Idantlflar  :  In  Clock_ID) ; 

procadura  Raaat_Ovarrun_Flag  (Clock_Idantlflar  :  In  Clock_ID) ; 

procadura  Sat_Xntarrupt_Pariod  (Clock_Zdantlflar  :  In  Clock_ZD; 

Pariod  :  in  KWV_COONTER_Typa) ; 

procadura  8tart__Counting  (Clock_Zdantifiar  :  in  Clock_ZD) ; 

procadura  Raad_Countar  (Clock_Idantifiar  :  In  Clock_XD; 

Wumbar_Of_Ticka  :  out  KWV_C00NTER_Typa) ; 
procadura  8top_Counting  (Clock_Zdantifiar  :  In  Clock_XD; 

Mumbar_Of  _Ti ck a  :  out  KHV_CODNTER_Typa) ; 
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function  Interrupt s_Enabled 
function  Current_Mode 
function  Current_Rate 
function  Znt«rrupt_P«riod 
function  Znterrupt_Flag_On 
function  Ova rrun_Flag_Qn 


(Clock_Xdentifier 
(Clock_I dent if ior 
(Clock_Identifier 
(Clock_Xdentifier 
(Clock_Identifier 
(Clock  Identifier 


In 

Clock  ID) 

return 

BOOLEAN; 

in 

Clock_ 

ID) 

return 

Clock_Mode; 

in 

Clock_ 

ID) 

return 

Clock_Rate; 

in 

Clock_ 

ID) 

return 

KWV  COUNTER  Type; 

in 

Clock_ 

ID) 

return 

BOOLEAN; 

in 

Clock 

ID) 

return 

BOOLEAN; 

Invalid_Clock_Mode  :  EXCEPTION; 
Initiali*ation_Error  :  EXCEPTION; 
Clock_Not_Xnitialized  :  EXCEPTION; 

private 

subtype  Clock_ID_Range  is  NATURAL  range  0 . .31; 
type  Clock_ID  is  new  Clock_ID_Rangs; 

end  KWVll_Clock_Manager; 


A.d.  KWV11_Clock_Manager  Package  Body 


SEI  Ada  Embedded  Systems  Project  Prologue 


—  Unit  name 

—  Experiment  f 

—  Version 

—  Author 

--  Date  created 

—  Last  update 

—  Host  Machine 

—  Target  Machine:  VAXELN  2.3 


KWV1 l_Clock  Manager  package  body 
PA01 
1.0 

Mark  W.  Borger 
17  Mar  1987 


VAXELN /VMS  4.5 


—  Abstract  This  package  body  implements  the  subprograms  of  its 

- :  specification.  It  maintains  a  Clock_ID  array  containing 

- :  the  corresponding  clock's  CSR  address  to  allow  for  the 

- :  control  of  sultiple  clocks . 

-  Revision  History  - 

—  Date  Version  Author  History 

—  22  Mar  87  1.0  Mark  W.  Borger  Added  data  structure  to  contain 

Mode  and  Rate  for  each  Clock  ID. 


Bad  of  Prologue 


package  body  KWVll_Clock_Manager  is 


—  Local  Data  types 


type  Clock_Information_Record  is  record 
Rate  :  Clock  Rate; 


ft 

g 

s? 

,r< 


Mode  :  Clock_Mode; 
and  record; 

type  Clock_Inf o_Array_Type  la  array (Clock_ID)  of  Clock_In£ormation_Racord; 
Clock_Info  :  Clock_Info_Array_Type  : -  (othars  ■>  (Stop,  Mode_Zero)); 

typa  ClooJc_Xrray_Typa  la  array (Clock_ID)  of  ADDRESS; 

Clock_Array  :  Clock_Array_Type  : ■  (otbara  ■>  ADDRESS_ZERO) ; 

Currant  Clock  Number  :  Clock  ID  : -  Clock  ID' FIRST; 


procadura  Inltlallza  (Clock_Name  :  in  STRING; 

Clock  Idantlfiar  :  out  Clock  ID; 


Mode  : 

in 

Clock_Mode; 

Rata  : 

in 

Clock  Rata; 

Vector_Number  : 

in 

VECTOR_NOMBER_TYPE ; 

Service  Routine  : 

in 

ADDRESS; 

CSR_Addraaa  :  out  ADDRESS; 

Devi ee_Obj act  :  out  DEVICE_TYPE  )  la  separate ; 

procadura  Ra_Initializa  (Clock_Idantif iar  :  in  Clock_ID; 

Moda  :  in  Clock_Moda; 

Rata  :  in  Clock_Rata  )  la  separate; 


procadura  Diaplay_CSR 
procadura  Enabla_Zntarrupta 
procadura  Diaabla__Xntarrupta 


(Clock_Idantifiar 
(Clock_Idantifier 
(Clock  Idantlfiar 


procadura  Sat_Intarrupt_Pariod  (Clock_: 


Idantlfiar 

Period 


procadura  Ganarata_Intarrupta  (Clock_Idantifiar 
procadura  Reaot_Intarrupt_Flag  (Clock_Idantifiar 
procadura  Raset_Ovarrun_Flacj  (Clock_Idantifiar 


In  Clock_ID)  la  separate ; 
in  Clock_ID)  la  separate; 
in  Clock_ID)  la  separate; 
in  Clock_ID; 

in  KWV_COUNTER_TYPE) is  separate; 
in  Clock_ID)  is  separate; 
in  Clock_ID)  is  separate ; 
in  Clock_ID)  is  separate; 


procadura  Start_Counting 
procadura  Raad_Countar 

procadura  8top_Counting 


(Clock_Idantif iar  :  in  Clock_ID)  is  separate; 

(Clock_Idantifiar  ;  in  Clock_ID; 

Number_Of_Ticks  :  out  KWV_COONTER_TYPE )  is  separate ; 

(Clock_Idantif iar  ;  in  Clock_ID; 

Numba r_Of_Ti ck s  :  out  KWV_COONTER_TYPE )  is  separate; 


function  Interrupt s_Enablad  (Clock_Idantlf iar  :  in  Clock_ID) 
return  BOOLEAN  is  separata; 

function  Currant_Moda  (Clock_Idantifiar  :  in  Clock_ID) 

return  Clock_Noda  la  separata; 

function  Currant_Rate  (Clock_Idantifiar  :  in  Clock_ID) 

return  Clock  Rata  is  separata; 


r*7*"*T*>  ■Vi 


function  Intarrupt_Pariod  (Clock_Idantif iar  :  in  Clock_ID) 
rtturn  KWV_COUNTER_TYP E  ia  aaparata; 

function  Xntarrupt_riag_On  (Clock_Xdantifiar  :  in  Clock_ID) 
ratum  BOOLEAN  ia  aaparata; 

function  Ovarr-un_Flag_On  (Clock_Idantif iar  :  in  Cloek_ID) 
ratum  BOOLEAN  ia  aaparata; 

and  KWVH_Clock_Managar; 


Initialize  procedure 

with  UNCHECKED_CONVERS I ON ; 

with  VAXELN_SERVICES ;  uaa  VAXELN_SERVICES; 

with  KWV_Ragiatar_Daf initiona ;  uaa  KWV_Ragiatar_Daf initiona; 

aaparata  (KWVH_Clock_Managar) 

procadura  Initialica  (Clock_Naaa  :  in  STRING; 

Clock_Idantifiar  :  out  Clock_XD; 

Mo  da  :  in  Clock_Moda; 

Rata  :  in  Clock_Rata; 

Vactor_Numbar  :  in  VECTOR_NUMBER_TYPE; 

Sarvica_Routina  :  in  ADDRESS ; 

CSR_Addraaa  :  out  ADDRESS; 

Davica_Objact  :  out  DEVICE__TYPE  )  ia 

Ratum  Coda  :  COND  VALUE  TYPE; 

KWVll_CSR_Addraaa  :  ADDRESS; 

CurrantCSR  :  KWV_CSR  Racord; 

Timar_Davica  ;  DEVTCE_ARRAY__TYPE (0 . . 0)  :■  (othara  ->  0) ; 

function  Convart_It  ia  naw  UNCHECXEDjCONVERSION (Clock_Moda,  DNSIGNED_2) ; 
function  Convart_It  ia  naw  UNCHECKED_CONVERSXON (Clock_Rata ,  DNSIGNED_3) ; 

bagin 


Craata  tha  KWV11-C  davioa  objaat  and  aaaociata  with  ita  intarrupta  tha 
Xntarrupt  Sarvica  Rout in a . 


Craata_Davica  (Statua  »>  Ratum Coda , 

Davica_Naroa  *>  Clock_Nama, 

Vactor_Numbar  «>  Vactor_Numbar, 

8arvica_Routina  ■>  Sarvica_Routina, 

Ragiatara  ■>  KWVH_CSR_Addraaa, 

Davica_Array  ■>  Tiraar_Davica, 

Davica_Count  «>  1) ; 

if  OONDXTION_HANDLING.8uccaaa  (Ratum_Coda)  than 

Davica_Objact  ;■>  Ti»ar_Davica (0) ; 

Ciock_Xdantifiar  : «  Curran t_ClockJNuabar; 

CSR_Addraaa  :■  FHVll_CSR_Addraaa; 

Clock_Array (Currant_Clock_Numbar)  :«  KWV1 l_CSR_Addra  a  a ; 

Clock_Info (Currant_Clock_Numbar)  :■  Clock_Xnformation_Racord' (Rata,  Moda) 

Currant  Clock  Nuxobar  :■  Currant  Clock  Numbar  +  Clock  ID (1) ; 


—  Initialica  clock  wia  CSR  aattinga 
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Curr*nt_CSR  :■  KWV_CSR_R*cord ' ( 

go  “>  FALSE , 

nod*  «>  Conv*rt_It (Mod*) , 

rat*  ■>  Conv*rt_It (Rat*) , 

others  «>  FALSE  ) ; 

Put_CSR (Curr*nt_CSR,  KWV1 l__CSR_Addr* as , ; 

•la* 

rala*  Initialization_Error; 

•nd  if; 


and  Initialise; 

pragma  INLINE (Initialize ) ; 


Rejnitiallze  procedure 

with  ONCBECXED_CONVERS I ON ; 

with  VAXELN_SERVICES;  us*  VAXELN_SERVICES; 

wit-h  KWV_R*giater_D*finitiona;  us*  KWV_Register_Def initions ; 

saparat*  (KWVll_Clock_Manager) 

procedure  Reinitialize  (Clock_Id*ntif i*r  :  in  Clock_ID; 

Mod*  :  in  Clock_Moda; 

-  Rat*  :  in  Clock_Rat*)  is 

Curr*nt_CSR  :  KWV_CSR_R*cord  C*t_CSR (Clock_Array (Clock_Identif ior) ) ; 

function  Conv*rt_It  ia  new  ONCBECXEDjCONVERSION (Clock_Mode,  UNSIGNED_2) ; 
function  Conve rt_It  la  n*w  UNCHECICED_CONVERSIOK (Clock_Rat* ,  UNSIGNED_3) ; 

begin 


If  specified  dock'*  CSR  addreaa  ia  non-zero  (i.e.,  the  clock  exists 
and  has  b**n  initialized)  than  re- in it is lire  it  by  clearing  the  CSR 
••ttinga;  otherwise  raise  an  exception  sine*  the  specified  clock  has 
—  not  been  initialized  proparly. 


if  Clock_Array (Clock_Id*ntifi*r)  /«  ADDRESS_ZERO  then 

Current_CSR  : “  KWV_CSR_Racord' (go  =>  FALSE, 

mod*  “>  Conv*rt_It (Mode) , 
rat*  «>  Conv* rt_It (Rate) , 
others  “>  FALSE  ) ; 

Put_CSR (Current_CSR,  Clock_Array (Clock_Id*ntifier) ) ; 

Clock_Info (Clock_Id*ntif ier)  : =  Clock_Information_Record' (Rate, Mode) 

•la* 

raise  Clock_Not_Initializ*d; 

•nd  if; 

•nd  R*_Initializ«; 

pragma  INLINE (R*_Initializ«) ; 
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Display_CSR  procedure 

with  TEXT_IO;  Ui«  TEXT_IO; 

with  KWV_Regiater  Definitions;  uae  KWV_Regiater_Def initiona ; 
with  UNciECKED_CoirVERS  I  ON  ; 

••pa rat*  (KWV1 l_Clock_Manager) 

procedure  Diaplay_CSR  (Clock_Identif ier  :  in  Clock_ID)  ia 

Current_CSR  :  KWV_GS R_Re  co  rd  : -  Get_CSR (Clock_Array (Clock_Identifier) ) ; 

package  Rat«_IO  ia  naw  ENUMERATION  10 (Clock_Rata) ; 
package  Mode_IO  ia  naw  ZNUMERAT I 0N~I 0 ( Cl ock_Mode ) ; 
package  BOOIiXN_IO  ia  new  ENUMERATI0N~I0 (BOOLEAN) ; 

function  Convert_It  ia  naw  UNCHECKED  CONVERSION (UNSIGNED_2 ,  Clock_Moda) ; 
function  Convert_It  ia  naw  UNCHECKED~C0NVER8I0N (UNSIGNED_3,  Clock_R*ta) ; 

procedure  Format ted_String_Put (Str  :  in  STRING)  ia 
begin 

Put (Str)  ; 

Set_Col (20)  ; 

Put("  ■>  ")  ; 

end  Format ted_String_Put; 

pragma  INLINE (Formattad_String_Put) ; 

begin 


If  apecified  dock' a  CSR  addreaa  ia  non-xero  (i.e.,  the  clock  exiata 
and  ha a  been  initialized)  then  diaplay  content  a  of  CSR  ; 
otherwiae  raiae  an  exception  aince  the  apecified  clock  haa 
not  been  initialixed  properly. 


if  Clock_Array  (Clock_Identif ier)  /-  ADDRESS_ZER0  then 
Forma tted_8tring_Put ( "CSR . go" ) ; 

BOOLEAN_IO . Put (Current_CSR . go) ;  New_Line ; 

Forma tted_String_Put ( "CSR . mode" ) ; 

Node_IO . Put (Convert_It (Current_CSR.mode) ) ;  New_Line; 
Formatted_String_Put ("CSR . rate" ) ; 

Rate_IO.Put (Convert_It (Current_CSR. rate) ) ;  New_Line; 

Formatted_String_Put ( "CSR . int_ovf " ) ; 

B00LEAN_I 0 . Put (Current_CSR . int_ovf ) ;  New_Line ; 

Formatted_String_Put ( "CSR . ovf_f lag" ) ; 

B00LEAN_I0 . Put (Current_CSR . ovf_f lag) ;  New_Line ; 

Formatted_8tring_Put ("CSR.maint_atl") ; 
BOOLEAN_IO.Put(Current_CSR.maint_atl) ;  Hew_Line; 

Formatted_8tring_Put ( "CSR . maint_at2 " ) ; 

BOOLEAN_IO.Put (Current_CSR.maint_at2) ;  Hew_Line; 

Formatted_String_Put ( "CSR . naint_oac " ) ; 

BOOLEAN_IO . Put (Current_CSR. maint_oac) ;  New_Line; 

Formatted_8tring_Put ( "CSR . dio " ) ; 

BOOLEAN  10. Put (Current  CSR. dio);  New  Line; 


r 

f 


Formattad_8tring_Put ( "CSR . £lag_overrun" ) ; 

BOOLEAN_IO . Put (Currant_CSR. flag_ovarrun) ;  Naw_Lina; 

I,ormattad_String_Eut  ( "CSR .  st2_go_enable" )  ; 

BOOLEAN_IO . Rut (Current_CSR. st  2_go_en*bl • ) ;  New_Line ; 

Forma ttad_Str in g_Put ( "CSR . st2_int_enable" ) ; 
BOOI£AN_IO.Put  (Current_CSR .  at 2_int_anable )  ;  Naw_Line 

Formattad_String_Put ( "CSR . st2_f lag" )  ; 

BOOLEAN_IO . Put (Currant_CSR . st2_flag) ;  New_Line; 

•la* 

raiaa  Clock_Not_Initialixed; 
and  1 f; 

and  Display  CSR; 


Enable  Jnterrupts  procedure 

with  KWV_Register_Definitions;  us*  KWV_Register_Def initions ; 
separate  (KWVll_Clock_llanag*r) 

procedure  Enable_Interrupta  (Clock_Idantifiar  :  In  Cloclc_ID)  is 

Curr*nt_CSR  :  KWV_CSR_R*eord  GatjCSR (Clock_Xrray (Clock_Identif i*r) ) ; 
bagln 

—  If  sp*cifl*d  clock's  CSR  addrass  is  non-xero  (i.a.,  tha  clock  axlsts 
—  and  has  baan  initialixad)  than  anabla  interrupt a  on  counter  overflow; 
otharwisa  raise  an  excaption  since  tha  spacif iad  clock  has 
not  baan  initialixad  proparly. 

if  Clock_Array(Clock_Idantifiar)  /«  ADDRE SS_ZERO  than 
Currant_CSR . int_ovf  : m  TROT ; 

Put_CSR (Current_CSR,  Clock_Array (Clock_Idantif iar) ) ; 

•Isa 

raise  Clock_Not_Initialix*d; 
and  if; 

and  Enabla_Intarrupts; 

pragma  INLINE (Enable  Interrupts) ; 


Disablejnterrupts  procedure 

with  KWV_R*gistar_Dafinitions;  use  KWV_Ragister_Def initions ; 
separata  (KWVH_Clock_Nanagar) 

procedure  Dlsabla_Intarrupts  (Clock_Xdantifiar  :  in  Clock_ID)  is 

Currant  CSR  :  KMV  CSR  Record  :■  Gat  CSR (Clock  Array (Clock  Identifier) ) 
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If  •pacified  cloak's  C8R  address  la  non-zero  (i.a. ,  tha  clock  exists 
and  baa  baa n  initialized)  than  disable  interrupts  on  counter  overflow; 
otherwise  raise  an  exception  sinee  the  specified  clock  has 
—  not  been  initialized  properly. 


if  Clock_Array (Clock_Identif ier)  /-  ADDRESS_ZERO  then 
Current_CSR. int_ovf  ;«  FALSE; 

Put_CSR (Current_CSR,  Clock_Array (Clock_Zdentif ier) ) , 

else 

raise  Clock  Not_Initialized; 
end  if; 

end  Disable__Interrupts; 

pragma  INLINE (Dlsable_Interrupts) ; 


SetJnterrupt_Period  procedure 

with  ONCHECKED_CONVERS I ON ; 

with  VAXELN_SEKVICES;  use  VAXELN_SERVICES; 

with  KWV_Register__Def initiona ;  use  KWV_Register_Def initiona; 

separate  (KWVH_Clock_Hanager) 

procedure  Set_Intarrupt_Pariod  (Clock_Identifier  :  in  Clock_ID; 

Period  :  in  KWV_COUNTER_TYPE )  is 

Device_Ticks  :  KWV_COONTER_TYPE; 

for  DeviceJTicks  use  at  (Clock_Array (Clock_Identif ier)  +  2 ) ; 
begin 


If  specified  clock's  CSR  address  is  non-zero  (l.e.,  the  clock  exists 
—  and  has  been  initialized)  then  set  the  current  value  of  the  clock 
interrupt  period  using  two's  complement  notation;  otherwise  raise 
an  exception  since  the  specified  clock  has  not  been  initialized  properly. 


if  Clock_Array (Clock_Zdentifier)  /“  ADDRESS_ZERO  then 
WRITE_REGISTER( (16#FFFF#  -  Period  +  1),  Device_Ticks) ; 

else 

raise  Clock  Not_Initialized; 
end  if; 

end  Set_Interrupt_Period; 

pragma  INLINE (Set  Interrupt  Period); 


Generatejnterrupts  procedure 

with  KMV_Register_Definltions;  use  KWV_Ragister_Def initiona ; 
separate  (KNVH_Clock_Manager) 

procedure  Ganerate_Interrupts  (Clock_I dent if ier  ;  in  Clock_ID)  is 

Current_CSR  :  KHV_CSR_Record  :■  Cet_CSR (Clock_Array (Clook_Identifier) ) ; 

begin 


If  specified  clock’s  CSR  address  is  non-zero  (i.e.,  the  clock  exists 
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and  has  baan  initialisad)  than  start  intarnal  oo untar  which  causa* 
intarrupts ;  otharwisa  raisa  an  axcaption  sinoa  tha  spacifiad  clock  has 
not  baan  initialisad  proparly. 


if  Clock_Array(Clock_Xdantifiar)  /-  XDDRZSS_ZERO  than 
Currant_CSR.go  : «  TRUE; 

Put_CSR (Currant_CSR,  Clock_Array (Clock_ldantif iar) ) ; 

alsa 

raisa  Clock  Mot  Initialisad; 
and  if; 

and  Canarata_Intarrupts; 

pragma  INLINE (Ganarata_Xntarrupts) ; 


Reset_lnterrupt_Flag  procedure 

with  KWV_Ragistar_Daf initions;  usa  KWV_Ragistar_D«f initions ; 
saparata  (KWVll_Clock_Managar) 

procadura  Rasat_Xntarrupt_Flag  (Clock_Idantifiar  :  in  Clock_ID)  is 

Currant_CSR  :  KWV_CSR_Racord  Gat_CSR (Clockjfcrray (Clock_Idantifiar) ) ; 

bagin 


If  spacifiad  clock's  CSR  addrass  is  non-taro  (i.a.,  tha  clock  azists 

—  and  has  baan  initialisad)  than  claar  countar  ovarflow  flag  to  allow 
anothar  intarrupt  to  ba  ganaratad;  otharwisa  raisa  an  axcaption  sinca 

—  tha  spacifiad  clock  has  not  baan  initialisad  propa^ly. 


if  Clock_Array(Clock_Xdantifiar)  /-  *DDRESS_ZERO  than 
Currant_CSR.ovf_flag  :■  FALSE; 

Put_CSR  (Currant_CSR,  Clock_Array  (Clock_Idantif iar) )  ; 

alsa 

raisa  Clock_Not_Initialirad; 
and  if; 


and  Rasat_Intarrupt_Flag; 

pragma  INLINE (Rasat_Intarrupt_Flag) ; 


Reset_Overrun_Flag  procedure 

with  KHV_Ragistar_Dafinitions;  usa  KWV_Ragi star_Daf initions ; 
saparata  (KWVll_Clock_Msnsg*r) 

procadura  Rasat_Ovarrun_Flag  (Cloak_Idantif iar  ;  in  Clock_XD)  is 

Currant_CSR  :  KHV_CSR_Racord  ; «  Oat_CSR(Clock_Array (Clock_Idantifiar) ) ; 


If  spacifiad  dock's  CSR  addrass  is  non-saro  (i.a.,  tha  clock  azists 
and  has  baan  initialisad)  than  claar  intarrupt  ovarrun  flag; 
otharwisa  raisa  an  axcaption  sinoa  tha  spacifiad  clock  has 
not  baan  initialisad  proparly. 


bag  in 


if  Clock_Array  (Clock_Idantifiar)  /»  ADDRXSS_IERO  than 
Cu  rrant_CgR . flag_ovarrun : ■  FALSI; 

Put_CSR  ( Curran  t_CSR,  Clock_Array (Clock_Idantif iar) ) ; 

alsa 

raiaa  Clock_Not_Initializad; 
and  if; 

and  Ra»at_Ovarrun_Fl«ij; 

pragma  INLINE (Rasat_Ovarrun_Flag) ; 


Start_Countlng  procedure 

with  KWV_Ragiatar_Daf initiona ;  usa  KWV_Ragistar_Daf initiona ; 
aaparata  (KWVll_Clock_Managar) 

procadura  Start_Counting  (Clock_Idantifiar  :  in  Clock_ID)  ia 

Currant_CSR  :  KWV_CSR_Racord  Gat_CSR (Clock_Array (Clock_Idantifiar) ) ; 

bagin 


If  apacifiad  clock' a  CSR  addraaa  is  non-Karo  (i.a.,  tha  clock  aziats 

—  and  has  baan  initializad)  than  start  tha  clock's  intamal  countar ; 

—  otbarwisa  raiaa  an  axcaption  sinca  tha  apacifiad  clock  has 

—  not  baan  initializad  proparly. 


if  Clock_Array (Clock_Idantif iar)  /»  ADDRESS_ZERO  than 

if  (Clock_Inf o (Clock_Idantif iar) .Moda  “  Moda_Two  or  alsa 
Clock_Info (Clock_Idantif iar) .Moda  ■  Moda_Zhraa) 

than 

Currant_CSR . go  :•  TRUE; 

PutjCSR  (Cur rant_CSR ,  Clock_Array  (Clock_Idantif iar) )  ; 

alsa 

rai sa  Invalid _ Clock_koda; 

and  if; 

alsa 

raiaa  Clock_Not_Initialirad; 
and  if; 

and  Start_Counting; 

pragma  INLINE (Start_Counting) ; 


Read_Counter  procedure 

with  KNV_Ragistar_Dafinitions;  usa  KWV_Ragistar_Dafinitions; 
s a pa rata  (KWVll_Clock_Managar) 

procadura  Raad_Countar  (Clock_Idantifiar  :  in  Clock_ID; 

Nuabar_Of_Ticka  :  out  KWV_COUNTER_TYPE)  is 

Curran t_GSR  :  KMV_CSR_Racord  :■  Gat_CSR (Clock_Array (Clock_Idantif iar) ) 

Davica_Ticks  :  K¥V_COONTER_TYPI; 

for  Davica_Ticks  usa  at  (Clock_Array (Clock_Idantif iar)  +  2); 


igin 


If  specified  dock's  CSR  address  Is  non-uro  (1.*.,  ths  dock  exists 

—  snd  has  boon  initialized)  than  simulate  an  axtamal  svant  In  ordar  to 

—  gat  currant  valua  of  tha  clock'  Intamal  countar  written  to  tha 

—  BUTTER /PRESET  register  and  than  read  that  value  and  return  it  while 
tha  dock  continues  to  run;  otherwise  raise  an  exception  since  the 
specified  clock  has  not  been  initialized  properly. 


if  Clock_Xrray(Clock_Zdentifier)  /-  ADDRZSS_ZERO  then 

if  (Clock_Info (Clock_Identifier) .Mode  ■  Mode_Two  or  else 
Clock_Info(Clo«k_Idantifier) .Mode  ■  Mode_Three) 

then 

Currant_CSR . st2_int_enable  : “  FALSE; 

Current_CSR . maint_st2  ;■  TRUE; 

Put_CSR (Current_CSR,  Clock_Array (Clock_Identifier) ) ; 
loop 

Current_CSR  : «  Get_CSR (Clock_Array (Cloek_Identifier) ) ; 
exit  when  Current_CSR. at2_flag; 
end  loop; 

Numbor_Of_Tieka  READ_REGI8TER (Device_Ticks) ; 
Current_CSR. st2_flag  : “  FALSE ; 

Put_CSR (Current_CSR ,  Clock_Array (Clock_Idantif iar) ) ; 

else 

raise  Invalid_Clock_Mode; 
end  if; 

else 

raise  Clock_Not_Initialized; 
end  if; 


and  Read  Counter; 


Stop_Countlng  procedure 

with  KWV_Register_Definitions;  use  KHV_Register_Definitions; 
separate  (KWVll_Clock_Manager) 

procedure  Stop_Counting  (Clock_Zdentif ier  :  in  Clock_ID ; 

Nuaber_Of_Ticks  :  out  KWV_COUNTER_TYPE )  is 

Current_CSR  ;  KWV_CSR_Record  :•  Cet_CSR (Clock_Array (Clock_Identif ier) ) ; 

Device_Ticks  :  KMV_CODNTER_TYPE ; 

for  Device_Ticks  use  at  (Clock_Array (Clock_Identif ier)  +  2) ; 

begin 


It  specified  dock's  CSR  address  is  non-zero  (i.e.,  the  clock  exists 

—  and  has  been  initialized)  then  simulate  an  external  event  in  order  to 

—  get  current  value  of  the  clock'  internal  counter  written  to  the 

—  BUFFER/PRESET  register  and  then  return  that  value; 

—  otherwise  raise  an  exception  since  the  spedfied  clock  has 

—  not  been  initialized  properly. 
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if  Clock_Array (Clock_Idantlfiar )  /-  AflCRESS_EERO  than 

if  (Cloek_Info (Clook_Idontif ia* )  Ibdt  ■  ldoda_Twc  or  alaa 
Ciock_Info (Clook_Idantlf lor )  Hod*  “  Hoda_Thraa) 

than 

Cur rantCSR  .  at2_int_anabla  “  riUl 
Curiut_Cn .  Miat_(t:  o  TOOK 

Put_CKR  (Cur rant_CSR .  ClockArray  (Clookldantlf iar)  )  ; 
loop 

CurrantCSR  : a  OatCSR (ClockArray (Clookldantlf iar) ) ; 
axit  Mhao  Curr*ot_CSR  it2_f U9 
and  loop; 

Nuabar_Of_Ticka  : -  READ_REGiaTZR (Dawioa_Tlcka) ; 

Cur rant _CSR .go  : ■  riLiX . 

Currant_CSR . at2_f lag  :■  FALSE 

Put _CS» (Cur rant _C8R,  Clock_Array (Clock_Idantif iar ) ) ; 

alaa 

raiaa  Inwalid_Clock_Hoda; 
and  if; 

alaa 

raiaa  Clock_Not_Initialirad; 
and  if; 

and  St op  Count  in g ; 


lnterrupts_Enabled  function 

with  KWV_Ragiatar_Daf initiona ;  uaa  EHV_Bagietar_Daf initiona ; 
aaparata  (KWVll_Clock_Managar) 

function  Zntarrupta_Enablad  (Clock_Idantif iar  :  in  Clock_ID)  rat urn  BOOLEAN  ia 
Currant_CSR  :  KWV_CSR_Racord  :■  GatjCSR (Clock_Array (Clock_Idantif iar) )  ; 

bagin 


If  apacifiad  dock' a  CSR  addraaa  ia  non-iaro  (i.a.,  tha  clock  axiata 
and  ha a  bo an  initializad)  than  rat urn  a  BOOLEAN  valua  Indicating 
whathar  or  not  tba  clock  will  ganarata  an  intarrupt  whan  ita  intamal 
clock  owarflowa;  oworflow  flag;  otharwiaa  raiaa  an  axcaption  ainca 
tha  apacifiad  clock  haa  not  boon  initialirad  proparly. 


if  Clock_Array (Clock_Idantifiar)  /a  ADDRESS_ZERO  than 
ratum  Currant_CSR .  int_ovf  ; 

alaa 

raiaa  Clock_Not_Initialisad; 
and  if; 

and  Intarrupta_Enablad; 

pragaa  INLINE (Intarrupte_Enablad) ; 


Current_Mode  function 

with  0NCHE CKED_COWVERS  ION; 

with  KWV_Ragiatar_Daf initiona ;  uaa  KWV_Ragiatar_Daf initione ; 
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aaparata  (KWV1  l_Clock_Managar) 

function  Currwitjloda  (Clock_Idantif iar  :  in  Clock_ID)  rat urn  Clock_Moda  1 
Currant_CSR  :  KWV_CSR_Racord  :■  Gat_CSR (ClockJLrray (Clock_Idant if iar) ) ; 

function  Conrart_It  ia  oav  U»CHECKID_CONVIRSION (UNSIGNED_2 ,  Cloek_Moda) ; 
bagin 


If  apaciflad  clock'*  CSR  addraaa  ia  non-iaro  (i.a.,  tha  clock  aziata 
and  ha a  baan  initial i sad)  than  ratum  currant  clock  noda; 

—  otharwiaa  raiaa  an  azcaption  ainoa  tha  apaciflad  clock  haa 
not  baan  initialicad  proparly. 


if  Clock_Xrray (Clock_Idantif iar)  /■  ADDRlSS_2ERO  than 
ratum  Con va rt _I t  (Cur rant _CSR. aaxia)  ; 

alaa 

raiaa  Clock_Not_Initializad; 
and  if; 

and  Currant_Moda ; 

pragma  INLINE (Currant  Moda) ; 


Current_Rate  function 

with  UNCHECKED_CONVERS I ON ; 

with  KWV_Ragiatar_Daf initiona;  uaa  KWV_Ragiatar_Daf initiona ; 
aaparata  (KWVll_Clock_llnnagar) 

function  Currant_Rata  (Clock_Idantif iar  :  in  Clock_ID)  ratum  Clock_Rata  i 
Currant_CSR  ;  KWV_CSR_Racord  :«  Gat_CSR (Clockjkrray (Clock_Idantif iar) ) ; 

function  Convart_It  ia  naw  UNCHECXED_CONVERSION (0NSIGNED3 ,  Clock_Rata) ; 
bagin 


If  apaciflad  clock's  CSR  addraaa  ia  non-zaro  (i.a.,  tha  clock  axiats 
and  haa  baan  initializad)  than  ratum  currant  clock  rata; 
otharwiaa  raiaa  an  azcaption  ainoa  tha  apaciflad  clock  haa 
not  baan  initializad  proparly. 


if  Clock_*xray (Clock_Idantif iar)  /■  ADDRESS_2ERO  than 
ratum  Convart_It  (Currant_CSR.  rata)  ; 

alaa 

raiaa  Clock_Not_Initializad; 
and  if; 

and  Currant_Rata; 

pragma  INLINE (Currant_Rata) ; 


lnterrupt_Perlod  function 

with  UWCHZCXZD_CCWVERSION; 

with  VAXELN_SEKVI CXS ;  uaa  VAXZLN_SZRVICZS; 

with  KWV_Ragiatar_Daf initiona;  uaa  KWV_Ragiatar_Daf initiona ; 

aaparata  (KWVll_Clock_Managar) 
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function  Znterrupt_Period  (Clock_Zdentifier  :  in  Cloek_ZD)  return  KWV_coUNTER  TYPE  is 
Devioe_Ticks  :  KWV_COONTER_TYPE  ; 

for  Devica_Tiaks  us*  at  (Clock_Axr*y (Clock_Identif lor)  +  2) ; 
begin 


if  specified  clock's  CSR  address  is  non-zero  (i.e.,  the  clock  exists 
end  hes  been  initialized)  then  return  current  value  of  the  clock 
interrupt  period;  otherwise  raise  an  exception  since  the  specified 
clock  has  not  bean  Initialised  properly. 


if  Clock_Array (Clock_Zdentif ier)  /-  ADDRESS_ZERO  then 
return  READ  REGISTER (Device_Ticks) ; 

else 

raise  Clock  Not_Xnitialised; 
end  if; 

end  Znterrupt_Period; 

pragma  INLINE (Znterrupt_Period)  ; 


lnterrupt_Flag_On  function 

with  KWV_Register_Def initions;  use  KWV_Register_Def initions ; 
separate  (KHVH_Clock_Manager) 

function  Interruptjriag_On  (Clock_Zdentifier  :  in  Clock_ID)  return  BOOLEAN  is 
Current  CSR  :  KWV  CSR  Reco r d  GetjCSR (Clock_Array (Clock_Identif ier) ) ; 

begin 


Zf  specified  clock’s  CSR  address  is  non-zero  (i.e.,  the  clock  exists 
and  has  been  initialised)  then  return  current  BOOLEAN  value  of  counter 
—  overflow  flag;  otherwise  raise  an  exception  since  the  specified  clock 
has  not  been  initialised  properly. 


if  Clock_Array(Clock_Zdentifier)  /-  ADORE  SJ>_  ZERO  then 
return  Cur rent_CSR . ovf_f lag ; 

else 

raise  Clock_Not_Initialized; 
end  if; 

end  Xnterrupt_Flag_On; 

pragma  INLINE (Interrupt_Flag_On) ; 


Overrun_Flag_On  function 

with  KMV_Register_Definitioas;  use  KWV_Register_Def initions ; 
separate  (KWVll_Clock_Manager) 

function  Ova rrun_r lag_On  (Clock_Zdentifier  :  in  Clock_ZD)  return  BOOLEAN  is 
Current_GSR  :  KWV_CSR_Reoord  : »  Get_CSR (Clock_Array (Clock_Zdentifier) ) ; 

begin 


Zf  specified  clock's  CSR  address  is  non-zero  (i.e.,  the  clock  exists 
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Appendix  B:  Examples  of  KWV11-C  Interface 


B.a.  Mode  0  Operation 

with  SYSTEM;  us*  SYSTEM; 

with  TEXT_IO;  uae  TEXT_IO; 

with  CALENDAR;  use  CALENDAR; 

with  KWVll_Clock_Manager;  m*  KWVll_Clock_Managor; 

with  VAXELN_SERVI CES  ; 

with  CONDITION_HANDLING; 

with  UNCHECRED_CONVERS ION  ; 

with  Timer_Intarrupt_Routina; 

procedure  ModeO_Tast  ia 

Clock_Name  :  con at ant  STRING  "FWV11"; 

Log_Fil#_Name  ;  constant.  STRING  : “  "25 :  :pa :  [borger] modeO_test .  log"  ; 

LogFila  :  riLEJTYPE; 

My_Clock_ID  :  Clock_ID; 

My_Clock_Device  ;  DEVI CE_TYPE ; 

CSR  :  ADDRESS; 

Tick a  :  KWV_COONTER_TYPE  :  «=  KWV_COONTER_TYPE (100) ; 

R*tum_Cod«  :  COND_VALCE_TYPE; 

Raault_Coda  :  INTEGER; 

subtype  Date_Time_Type  ia  VAXELN_SERVXCES.Date__Time_Type; 

f unction  Futur«_Tima  (Time_Interval  :  Day_Duration)  return  Date_Time_Type  ia 
function  Time_To_Date_Tlma  ia  new  UNCHECKED_CONVERS ION (Time , ~Date_Time_Type ) 
begin 

return  Tim#_To_Date_Tima (Clock  +  Tima_Interval) ; 
end  Futu  re_T ime ; 

begin 


—  Open  external  log  file  on  hoat 


Open (Log_File,  Out_F i 1 e ,  Log_File_Name) ; 
Set_Output (Log_File) ; 


Initialize  the  clock  to  operate  in  mode  zero  at  a  1MHZ  rate. 
—  The  Interrupt  Service  Routine  ia  "Timer_Interrupt_Routine" . 


Initialize  (Clock_Najae  *>  Clock_Name, 

Clock_Identif ier  ■>  My__Clock_ID, 

Mode  ">  Mode_Zero, 

Rate  ->  RatelMHZ, 

Vector_Number  ■>  1, 

8ervice_Routine  *>  Tiaer_Interrupt_Routine' ADDRESS, 
CSR_Addreaa  ->  CSR, 

Device_Object  ->  *y_  _Clock_Device  ) ; 


—  Enable  clock  overflow  aignala  (interrupt a) 


Enable_Xnterrupta  (My_Clock_ID)  ; 
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—  Sat  interrupt  tima  pariod  to  be  100  tick*  (microseconds) 


8et_Interrupt_Period (My_Clock_ID ,  Ticks) ; 

Tor  Index  in  1..100 
loop 


—  Start,  generating  the  interrupts  (in  this  case,  only  one  interrupt 
since  the  clock  is  operating  in  mode  0) . 


Generate_Interrupts  (My_Clock__ID)  ; 


—  Wait  for  a  signal  device  (kernel  service)  call  from  the 
Timer  Interrupt  Routine.  Timeout  after  5  seconds. 


VAX£LN_SER  VICES . WVIT_ANY  (Status  ->  Raturn_Coda, 

Result  ■>  Result_Code, 

Time  “>  i*uture_Time  (5.0), 
Valuel  "*>  My_C  1  o ck_De v ice  )  ; 


Determine  if  signal  device  (kernel  service)  call  was  made,  or  else 
we  timed  out  after  5  seconds . 


if  CONDITION_HANDLING.  Success  (Retum_Code)  and  then  Result_Code  =  1  then 
Put_Lina ("Device  Signal  received."); 

else 

Put_Line ("WAIT_ANY  timed  out."); 
end  if; 

end  loop; 


—  Stop  clock  operation 


Reinitialize (My_Clock_ID,  Mode_Zero,  Stop); 


—  Close  external  log  file  on  host 


Close (Log_File) ; 
exception 

when  Initialization_Error  •> 

Put_ULne ("Error  during  clock  initialization."); 
Close  (Log_File) ; 

when  Clock_Not__Initialized  »> 

Put_Line ("Invalid  clock  identifier."); 

Close  (l>og_rile)  ; 

when  others  “> 

Close (Log_File) ; 

end  ModeO  Test; 
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B.b.  Mode  1  Operation 

with  SYSTEM;  ua*  SYSTEM; 

with  TEXT_IO;  ua*  TEXT_IO; 

with  CALENDAR;  ua*  CALENDAR; 

with  KWVll_Clock_Managar;  ua*  KWVll_Clock_Man*g*r; 

with  VAXELN_SERVICES ; 

with  CONDITION_HANDLING; 

with  UNCHECKED_CONVERSION; 

with  Timar_Int«rrupt_Routin* ; 

procedure  Mod*l_T*at  ia 

Clock_Nan*  :  constant  STRING  "KW11"; 

Log_Fi le_Nam*  :  conatant  STRING  :■  "25 : :pa : [borger] mod*l_t*at . log" ; 

Log_Fil*  :  riLE_TYPE; 

My_Cloek_ID  :  Clock_ID; 

My _C 1 o  ck_D* v i c •  :  DEVI CE_TYP E ; 

CSR  :  ADDRESS; 

Ticks  :  KHV  COONTER_TYPE  KWV_CODNTER_TYFE (10_000) ; 

R*tum_Cod*  :  COND_VALDE_TYPE; 

R*sult_Cod«  :  INTEGER; 

subtyp*  Dat*_Tim*_Typ*  is  VAXELN_SERVICES . Dat*_Tim*_Typa; 

function  Future_Tim*  (Tima_Interval  :  Day_Dur*tion)  tstura  Dat*_Tima_Typ*  ia 

function  Tim*_To_D*t*_Tim*  ia  n*w  ONCHECKED_CONVERSION (Tim*,  Data_Tima_Typ«) ; 
begin 

ratum  Tima_To_Dat*_Tima (Clock  +  Tim*_Intarval) ; 
and  Futur*_Tima; 

bagin 


—  Opan  axtamal  log  fil*  on  host 


Opan (Log_Fila,  Out_Fil* ,  Log_Fil*_Nam*) ; 
S*t_Output (Log_Fil*) ; 


Initialize  tha  clock  to  operate  in  mode  isro  at  a  1MHZ  rat*. 
—  Th*  Interrupt  Sarvic*  Rout in*  is  "Timar_Int*r;rupt_Routin*" . 


Initialize (Clock_Naae  *>  Clock_Name, 

Clock_Id*ntifi*r  «>  My_Clock_ID, 

Mod*  *>  Mod*_On* , 

Rat*  *>  RatalMHZ, 

V*  ct  o  r_Numba r  «>  1, 

S*rvic*_Routine  “>  Timar_Int*rrupt_Routin* ' ADDRESS , 
CSR_Addr*ss  «>  CSR, 

Devi ca_Obj act  ■>  My_Cl ock_Davi ca  ) ; 


—  Enabl*  clock  overflow  signals  (interrupts) 


Enabl*_Znt*rrupta (My_Clock_ID) ; 


—  Sat  Interrupt  tim  period  to  b*  10_000  ticks  (microseconds) 


8*t_Intarrupt_P*riod (My_Clock_ID,  Ticks); 
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Start  ganarating  tha  intarrupta  (in  this  caaa,  rapaatadly 
ainoa  tha  dock  la  opa rating  in  mod*  1)  . 

Ganarata_Intarrupta  (My_Clock_ID)  ; 


—  Banda  100  intarrupta 


for  Zndax  in  1..100 
loop 


—  Wait  for  a  aignal  davica  (kamal  aarvica)  call  from  tha 
Tioar  Zntarrupt  Boutina.  Tima out  aftar  2  aaconda . 


VAXELN_SERVT  CIS .  WAIT_ANY  (Statua  ->  Ratum_Coda, 

Raault  ■>  Raault_Coda, 

Tima  ■>  Tutura_Tima (2.0), 
Valual  “>  Wy_Cloc)c_Davica  )  ; 


Raaat  intarrupt  flag  to  allow  mora  intarrupta  to  ba  ganaratad 


Raaat_Intarrupt_Flag (My_Clock_ID)  ; 


Datarmina  if  aignal  davica  (kamal  aarvica)  call  waa  nada,  or  alaa 
wa  timad  out  aftar  2  aaconda . 


if  CONDITION_HANDLING. Succaaa (Ratum_Coda)  and  than  Baault_Coda  =  1  than 
Put_Lina ("Davica  Signal  racaivad. " ) ; 

alaa 

Put_Lina ("WAIT_ANY  timad  out."); 
and  if; 

ard  loop; 


—  Stop  clock  oparation 


Ra_Initializa (My_Clock_ID ,  Moda_Zaro,  Stop); 


—  Cloaa  axtamal  log  fila  on  hoat 


Cloaa (Log_Fila) ; 
ax caption 

whan  Initialization_Error  «> 

Put_Lina ("Error  during  clock  initialisation."); 
Cloaa (Log_Fila) ; 

whan  Clock_Not_Initialirad  ■> 

Put_Lina ("Invalid  clock  idantifiar . ”) ; 

Cloaa (Log^Fila) ; 

whan  othara  ■> 

Cloaa (Log_Fila) ; 

and  Modal  Taat; 
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B.c.  Mode  2  Operation 


with  SYSTEM;  us*  SYSTEM; 

with  TZXT_IO;  us*  TEXT_IO; 

with  KWVll_Clocjc_Manag*r ;  us*  KWVll_Clock_Man*ger; 


proosdurs  Mod*2_R*ad_T*st  is 


Clock_Naiae 

Log_File_Name 

Log_File 

My_Clock_Id 

“Y.  Clock_D*vic* 

CSR 

Ticks 


constant  STRING  : 

constant  STRING  : 

riLE_TYPE; 

Clock_ID; 

DEVICE_TYPE; 

ADDRESS; 

KWV  COUNTER  TYPE; 


"KWV11"; 

”25: :ps: [borger]moda2_read_test .log" 


bagin 


—  Op*n  sstsmal  log  fila  on  host 


Op«n (Log_File,  Out_Fil*,  Log_Fil*_Nama) ; 
S*t_Output (Log_File) ; 


Initialize  th*  clock  to  operate  in  mode  two  at  a  1MHZ  rata 


Initializa (Clock_Name  *■>  Clock_Nama , 
Clock_Idanti£iar  «>  My_Clock_ID, 

Mod*  — >  Moda_Two, 

Rat*  ■>  Ratal MHZ , 
V*ctor_Numb*r  *>  1, 

Service  Routine  “>  ADDRESS_ZERO , 
CSR_Addr a s s  ->  CSR, 

Davic*_Objact  *>>  My_Clock_D*vica  )  ; 


Repeatedly  naasura  overhead  tin*  associated  with  starting  and 
stopping  tha  clock's  counting;  record  this  overhead  time  in  the  log  file 


Start_Counting (My_Clock_ID)  ; 

for  Index  in  1 . . 500 

loop 

R*ad_Counter (My_Clock_ID,  Ticks) ; 
Put (INTEGER' IMAGE (INTEGER (Ticks) ) ) ; 

if  (Index  ram  10)  *  0  than 
N*w_lin* ; 
and  if; 
and  loop; 


—  Stop  clock  operation 


Ra_Initializa (My_Clock_ID,  Mod*_Z*ro,  Stop); 


—  Close  external  log  fil*  on  host 


Close (Log_File)  ; 
e caption 
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B.d.  Mode  3  Operation 

with  SYSTEM;  us*  SYSTEM; 

with  TEXT_IO;  us*  TEXT_IO; 

with  KWVll_Clock_Manager;  us*  KWV1 l_Clock_Manag*r; 


procedure  Moda3  T*st  is 


Clock_Nem* 

Log_File_Najna 

Log_rila 

My_Clock_Id 

**Y_  Clock_Device  : 

CSR  : 

Tick* 


constant  STRING  : “ 
constant  STRING 
FII£_TYPE; 
Clock_ID; 

DEVI CE_TYP E ; 
ADDRESS; 

KWV  COUNTER  TYPE; 


"KWV11" ; 

”25 :  :ps  :  [borge*']  mod*3_test .  log"  ; 


begin 


Open  axtamal  log  file  on  host 


Op*n (Log_Fil* ,  Out_Fil*,  Log_File_Nama)  ; 
S«t_Output (Log_Fil*) ; 


Initialize  tha  clock  to  operate  in  mode  three  at  a  1MHZ  rate 


Initialize  (Clock_Name  “>  Clock_Name, 
Clock_Identif i*r  *>  My_Clock_ID, 

Mode  ■«>  Mod*_Thr*e, 

Rate  ->  RatelMHZ, 
Vector_Number  «■>  1, 

Service_Routine  ■<>  ADDRESS_ZERO, 
CSR_Addres a  ->  CSR, 

D*vic*_Ob ject  •>  My_Clock_Devica  ) ; 


Repeatedly  asasurs  overhead  time  associated  with  starting  and 
stopping  the  clock's  counting;  record  this  overhead  time  in  the  log  file 


for  Index  in  1..500 
loop 

Start_Counting (My_Clock_ID) ; 
Stop_Countlng (My_Clock_ID,  Ticks) ; 
Put (INTEGER' IMAGE (INTEGER (Ticks) ) ) ; 
end; 

if  (Index  tea  10)  *  0  then 
Mew_line; 
and  i t; 
end  loop; 


Appendix  C:  Software  Measurement  Techniques  Using  the 
KWV11-C  Interface 

C.a.  Technique  #1 

with  SYSTEM; 
with  TEXT_IO; 
with  KHVll_Cloek_Manager; 
with  VJUCELN_SERVICES; 
with  CONDITION_HANDLING; 
with  Tia*r_Int*rrupt_Routin*  ; 

procedure  Mod* l_Wait_T iota  is 

Clock_Nama  :  constant  STRING  "KHVH”; 

My_Clock_ID  :  Clock_ID; 

My_Clock_Davica  :  DEVI CE_TYPE ; 

CSR  :  ADDRESS; 

Ticks  :  KWV_COONTER_TYPE  :*  KWV_COONTER_TYPE (5000); 

begin 


usa  SYSTEM; 
usa  TEXT_IO; 

usa  KWVll_Clock_Manag*r; 


Xnitialia*  tha  clock  to  oparata  in  mod*  taro  at  a  1MHZ  rata. 
Tha  Intarrupt  Service  Rout in a  \s  HTim*r_Int*rrupt_Routina" . 


Initialize (Clock_Nama  *»  Clock_Nama, 

Clock_Id*ntif iar  —>  My_Clock_ID, 

Mod*  *>  Moda_Z*ro , 

Rat*  ->  RatalMHZ , 

VactorNumbar  ■>  1, 

S*rvie*_Routin*  ■>  Tim*r_Int*rrupt_Routina' ADDRESS, 
CSR_Addr*ss  ■>  CSR, 

Da vi c* _ Ob j act  ■>  My_Clock_D*vio*  ) ; 


Loop  until  tha  clock's  overrun  flag  is  sot  which  will  indicate  that 
software  is  not  kaaping  up  with  tha  intarrupt  rata.  This  will  giva 
a  rough  ataasura  of  tha  alapaad  time  from  tha  time  of  tha  intarrupt 
until  tha  application  cod*  is  ra- scheduled  and  executed. 


loop 


R*-initializ*  clock 


Reinitialize  (My_Clock_ID,  Moda_0na,  RatalMHZ); 


—  Enable  clock  overflow  signals  (interrupts) 


Enabla_Intarrupts  (My_Clock_ID)  ; 


Decrees*  number  of  ticks  counted  to  ganarat*  an  intarrupt 
Ticks  KWV_COONTER_TYPE (INTEGER (Ticks)  -  1); 
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—  Program  clock  to  generate  interrupt  every  Tick*  microseconds 


8et_Interrupt_Period(My_Clock_ID,  Ticka) ; 


—  Start  ganaratlng  tha  interrupts  (In  thia  caaa,  rapaatadly 
alnca  tha  clock  ia  operating  in  moda  1) . 


Generate_Xnterrupts  (My_Clock_ID)  ; 


Wait  for  a  aignal  device  (kamal  service)  call  from  tha 
Timar  Interrupt  Routine. 


VXXELN_SERVICES.WXIT_ANY  (Valual  ->  My_Clock_Davica) ; 


Raaat  interrupt  flag  to  allow  store  intarrupta  to  be  generated 


Raaat_Intarrupt_riag (My_Clock_ID) ; 
exit  whan  Overrun_riag_On (My_Clock_ID)  ; 
and  loop; 

Put_Line (INTEGER' IMAGE (INTEGER (Ticka) ) )  ; 
—  Stop  clock  operation 


Reinitialise  (My_Clock_ID,  Mode  Zero,  Stop)  ; 


exception 

whan  Initialisation_Error  «> 

Put_Line ("Error  during  clock  initialisation.”); 

whan  ClockJNot_Initialised  “> 

Put_Line  (" Invalid  clock  identifier . “) ; 

when  others  »> 

Put_Llne ("Unexpected  exception  raised. ”)  ; 
and  Model  Wait  Time; 
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a  MicrovAXII/  VAXELN  2.3  target  system,  the  VAXELN  1.1  Ada  compiler,  and  a  KWV11-C 
programmable  real-time  clock.  It  provides  an  overview  of  VAXELN  interrupt  handlers  and 
the  operation  of  the  real-time  clock; discusses  and  demonstrates  the  use  of  VAXELN 
kernel  services  to  establish  a  link  between  the  clocks  interrupt  and  the  starting 
address  of  an  interrupt  service  routine;  presents  an  Ada  package  of  interfaces  to  the 
KWV11-C  device;  provides  Ada  source  code  examples  demonstrating  the  use  of  this  package; 
and  presents  relevant  observations,  recommendations,  and  measurement  results. 
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